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PREFACE 



RMX/80 is a user-configurable software package that provides a Real-time, 
Multitasking Executive for Intel Single Board Computer systems. It consists of a 
central Nucleus and a number of extensions that may be selected as required; 
together, these serve as a base for real-time application systems. RMX/80 operates 
on hardware systems based on the iSBC 80/20, 80/24, 80/30, and 80/ 10 computers. 

This manual is intended to serve two purposes: as an introduction to RMX/80 for 
the new user, often an applications programmer with little or no experience with 
operating systems or real-time programming; and as a reference manual supplying 
all the information necessary for interfacing with the RMX/80 Nucleus and exten- 
sions. 

Because of the intermixing of conceptual and detailed information, at least two 
readings of the User's Guide are recommended. On the first reading, you should 
skim over the detailed information and concentrate on gaining an understanding of 
the kinds of services that RMX/80 provides. On subsequent readings you can study 
the details of how to use these services. 

This User's Guide assumes that the reader is familiar with Intel Single Board Com- 
puter (iSBC) hardware, with programming techniques for 8080/8085-based systems, 
and with the ISIS-II conventions for program relocation and linking. (ISIS-II is the 
diskette operating system for the Intellec and Intellec Series II microcomputer 
development systems.) 

Companion Documents 

Other manuals and application notes that pertain directly to the RMX/80 executive 
are the following: 

• iRMX 80 Installation Instructions, 9803087. 

• iRMX 80 Interactive Configuration Utility User's Guide, 142603. 

• AP-33. RMX/80 Real-Time Multitasking Executive, 9800577. 

• AP-47. Using FORTRAN-80 for iSBC Applications, 9800836. 

• AP-52. Using Intel's Industrial Control Series in Control Applications, 9800932. 

• AP-88. Multiprocessing Extensions for the RMX/80 Real-Time Executive, 
142725. 



Related Publications 

The use of Intel Single Board Computer hardware, programming techniques for 
8080/8085-based systems, and ISIS-II relocation and linking conventions are 
discussed in the following manuals: 

• System 80/20-4 Microcomputer Hardware Reference Manual, 9800484. 
p System 80/30 Microcomputer Documentation Package, 9800707. 

• System 80/10 Microcomputer Hardware Reference Manual 98003 16. 

• 8080/8685 Assembly Language Programming Manual, 980030 1 . 
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• PL/M-80 Programming Manual, 9800268 . 

• ISIS-II User's Guide, 9800306. 

You will also generally need to use the ISIS-II PL/M compiler and/or the ISIS-II 
8080/8085 assembler; and you may wish to use one of the Intel In-Circuit 
Emulators, ICE-80 or ICE-85, during system development. The following Intel 
manuals provide the information you need to use these products: 

• ISIS-II PL/M-80 Compiler Opera tor 's Man ual, 9800300 . 

• ISIS-II 8080/8085 Macro Assembler Operator's Manual, 9800292. 

• In-Circuit Emulator/80 Operator's Manual, 98001 85 . 

• ICE-85 In-Circuit Emulator Operating Instructions for ISIS-II Users, 9800463 . 

In addition, certain RMX/80 extensions (including the Disk File System and the 
Analog Handlers) are designed to interface with specific Intel Single Board Com- 
puter hardware in addition to the processor boards. Reference is made in the ap- 
propriate chapters to the manuals required for the use of this additional hardware. 
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CHAPTER 1 
OVERVIEW 



Purpose of RMX/80 

RMX/80, Intel's Real-time, Multitasking Executive, provides a base around which 
you can build a real-time, multitasking application system. RMX/80 allows you to 
concentrate your major programming efforts on your particular application rather 
than on the problems of synchronizing multiple real-time tasks. 

RMX/80 is designed for Intel Single Board Computer (iSBC) systems based on the 
iSBC 80/20, iSBC 80/24, iSBC 80/30, or iSBC 80/ 10. The software, if made ROM- 
resident, is designed to initialize the system without a need for external storage 
media. Because RMX/80 has been designed specifically for Intel Single Board 
Computers, its memory requirements are appropriate for the microcomputer 
environment. The basic Nucleus requires less than 2K bytes of program storage and 
approximately 250 bytes of data storage. 



RMX/80 Features 

As can be seen in figure 1-1, RMX/80 is not a single, indivisible product. The heart 
of the system — the RMX/80 Nucleus — is supported by a number of additional 
software tools, or extensions, such as the Terminal Handler, Free Space Manager, 
Debugger, and Disk File System, which are designed to meet common real-time 
system requirements. Each RMX/80 extension is supplied as a separate module 
(task) or set of modules, so that you may select only those features you need for your 
particular application. To this collection of RMX/80 tasks you then add your ap- 
plication tasks. 




Figure 1-1. Modular Structure of an RMX/80 System 



The following paragraphs briefly describe the RMX/80 Nucleus and extensions. 
Each of these features is covered in detail in its own chapter later in this manual. 
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RMX/80 Nucleus 



The RMX/80 Nucleus directs and coordinates system operation. It initializes system 
control structures, determines which task should be executed next, supplies timing 
functions for the system, and provides a means for controlling and exchanging data 
within the system. User tasks communicate with the Nucleus by means of a set of 
RMX/80 primitive operations. 

Terminal Handler 

The Terminal Handler provides real-time asynchronous I/O between an operator's 
terminal and tasks running under the RMX/80 Nucleus. It includes a line-edit 
capability similar to that of ISIS-II and an additional type-ahead feature. (ISIS-II is 
the diskette supervisor system used on the Intellec Development System.) The Ter- 
minal Handler may be configured with full capabilities, for output only, or in either 
of two minimal versions that require considerably less code space. 

Free Space Manager 

The Free Space Manager maintains a pool of free RAM and allocates memory from 
that pool upon request from a task. The Free Space Manager also allows memory to 
be returned to the pool when it is no longer needed. 

Debugger 

The Debugger is designed specifically for debugging systems running under the 
RMX/80 Nucleus. A special debugger is needed for such systems, since the real-time 
software environment changes constantly in response to external events. The Debug- 
ger allows convenient access to RMX/80 data structures. It can be run in the Single 
Boards Computer's memory, or an in-circuit emulator such as ICE-80 or ICE-85 can 
be used to load and execute the Debugger. This last option allows use of the Debug- 
ger without imposing any memory requirements on the iSBC 80. 

If desired, the Debugger can be configured into an application system to provide for 
troubleshooting in the field. A limited-capability version of the Debugger is 
available for applications in which memory space is limited. 

Disk File System 

The Disk File System provides diskette processing capabilities which are similar to 
those available in ISIS-II. Files may be created, deleted and updated; data can be ac- 
cessed sequentially and directly ("randomly"). 



Analog Handlers 

The Analog Handlers provide analog input and output services for users whose 
systems interface with the iSBC 711, iSBC 724, and iSBC 732 analog boards. The In- 
put Handler task performs repetitive, sequential, and random channel input; the 
Output Handler task performs random channel output. 



Bootstrap Loader 

The Bootstrap Loader allows you to store your applications software on the disk 
rather than in ROM. This affords you two types of flexibility. First, since your 
applications software is stored on disk rather than in ROM, changes are easier to 
implement. Modifications to your applications software entail changing the con- 
tents of the disk rather than the contents of ROM. Second, since the disk has a much 
larger storage capacity than does the ROM, you can store multiple applications on 
disk and use the Bootstrap Loader to bring them into RAM as they are needed. 
Consequently, you can use a single iSBC for more than one application. 
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Command Line Interpreter 

The Command Line Interpreter enables ar operator at a terminal to start up various 
tasks by entering commands. 

The RMX/80 Product 

The RMX/80 product is supplied as a set of diskette files which include all the soft- 
ware (except ISIS-II and Intel language translators) required to prepare an 
RMX/80-based application system. The following types of files are included: 

• Relocatable and linkable object code for the RMX/80 Nucleus and extension 
tasks 

• INCLUDE files containing sections of PL/M code commonly needed in 
programming application systems 

• The PL/M library and a special RMX/80 unresolved reference library, required 
at link time to resolve external references 

• Files to support the RMX/80 Demonstration System, a sample program 
furnished for demonstration and checkout of the RMX/80 software (refer to 
Appendix I for description and operaling instructions) 

Appendix A provides a list of all files on the RMX/80 diskettes, with a brief descrip- 
tion of each. 

Characteristics of Real-Time Systems 

The simplest processing systems are batch systems . In a batch system, a number of 
operations are submitted at once to the processor and then performed in the se- 
quence submitted (or according to some other scheduling scheme) without respect to 
external events. In contrast, a real-time system responds to certain events in the 
"real world" as they occur. Interactive terminal systems and computerized process 
control systems are examples of real-time systems. 

Real-time processing imposes special requirements on the operating system that 
coordinates and schedules processing functions, as well as on the application pro- 
gram modules that perform these functions. This section of the chapter is provided 
to familiarize the user with the fundanuntal characteristics of real-time systems, 
with some specific references to the RMK/80 implementation. A basic understan- 
ding of these concepts is necessary in building an application system based on 
RMX/80. 

Asynchronous Operation and Synchronization 

Events to which a real-time system must respond may occur at unpredictable times 
and in unpredictable order. A system that responds to such events as they occur is 
said to execute asynchronously. Asynchronous operation requires synchronization 
of system functions with the individual events rather than with a system clock; i.e., 
one event (external to the system) causes another (the execution of a processing func- 
tion) to occur. It must be noted, however, that a system operating asynchronously 
may still need timing functions that require a clock. 

As an example of synchronization, consider a microcomputer-controlled system that 
weighs and stamps packages. One part of the system detects (by means of a sensor) 
the arrival of a package, weighs the package, and calculates pricing data. Price and 
weight data are then communicated to i:he stamping station. Since the amount of 
time required to move the package from the weighing station to the stamping station 
is known, the task that drives the stamping mechanism can wait the proper time in- 
terval and then trigger the stamping process. 
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In this example, the weighing and price calculation program is started when a 
package arrives at the weighing station; i.e., weighing and price calculation opera- 
tions are synchronized with the arrival of a package. The stamping process, similar- 
ly, is synchronized with the arrival of price and weight data at the stamping station 
— but only after a clock-driven timed wait operation is completed. 

The RMX/80 software provides for task synchronization by means of the 
message/exchange facility and the timed wait operation. Both of these features are 
described later in this chapter. 



Concurrency 

In a real-time system, several operations will generally be in progress at a given time. 
This concurrency of events is a distinguishing characteristic of real-time systems. As 
an example, consider the package weighing and stamping system discussed in the 
previous section. If a second package arrives at the weighing station about the same 
time as the first package is being stamped, the task directing the weighing of the sec- 
ond package may be performed concurrently with the task controlling the stamping 
of the first. 

When there is only one central processing unit, as in a system running under 
RMX/80, only one operation can have control at any given instant; however, it is 
not necessary that that operation be finished before a faster or more important 
operation takes control. The speed of the processor can make concurrent operations 
appear to be running simultaneously. 

The designer of a real-time system should identify the functions in his design that 
can be performed concurrently. These functions are known as tasks . The designer 
or programmer defines these tasks to a central operating system such as the 
RMX/80 Nucleus, which schedules and controls their operation. 

While the system is running, a task with an urgent need for the system's computing 
resources can preempt the currently executing task. When the new task has com- 
pleted its function (or must wait for another event or input), the central operating 
system automatically either continues the previously executing task or starts ex- 
ecuting some other task that currently has a greater need for the processor. 

For example, in a process control application the system might monitor the 
temperature of a paper feedstock and gauge the thickness of the stock as it passes 
through rollers. The system controls the process by varying the feedstock heaters 
and/or pressure rollers as required. Such a system would probably also display in- 
formation about the process at an operator's station; the operator must be able to 
enter new temperature and roller pressure specifications at any time. 

If this system is viewed as a series of sequential events, as it might be in a single, 
large program, the system performs the following functions: 

• Monitor feedstock temperature 

• Control heaters as required 

• Update operator's display 

• Monitor thickness 

• Control pressure rollers as required 

• Update operator's display 

• Accept input from operator's console 

• Control heaters and rollers as required 

• Update operator's display 

• Return to first step and begin again 



\-4 



RMX/80 



Overview 



Notice that in this "monolithic" approach, the processor cycles through the same 
code over and over. Considerable time can be spent checking for the occurrence of 
events that are asynchronous. For example, although the operator would normally 
enter data sporadically, the program checks for this every time it goes through its cy- 
cle. Notice also, that the program is only ' ready" to accept operator data at a fixed 
time— it is not capable of providing flexible; response to varying conditions. 

Using RMX/80 in this process control application, the programmer might identify 
the following concurrent events: 

• Monitor feedstock temperature 

• Control temperature 

• Monitor thickness 

• Control pressure rollers 

• Update operator's display 

• Accept input from operator's console 

The programmer would code a separate task for each concurrent event. RMX/80 
provides the coordination required to exec ute each task only as it is needed, that is, 
in response to an event. In this way the system can respond to varying load condi- 
tions and throughput potential is increased . 

The speed of the processor enables the sy stem to appear to be performing multiple 
tasks concurrently. A microprocessor executes thousands of instructions each sec- 
ond. Contrast this with an operator making an entry from a console keyboard. The 
operator probably enters only a few chciracters a second. The intervals between 
keystrokes give the system enough time to execute several of its monitor and control 
tasks. 



Priority 

When several tasks are competing for the central processor, the real-time system 
must determine which task is to run first — i.e., which task has highest priority . 
The system designer or programmer must therefore assign each task a priority level 
for use by the system. RMX/80 provides 256 software priority levels for tasks. 

Generally, tasks invoked by emergency conditions need to have higher priority than 
routine operations; tasks that execute rapidly or require quick response time require 
higher priority than slower or less urgent tasks; and tasks that service interrupts 
from peripheral devices should usually have higher priority than processing tasks in- 
voked by other tasks. 

In our process control application, for example, priorities might be assigned as 



follows: 


1. 


Monitor thickness 


2. 


Control pressure rollers 


3. 


Monitor temperature 


4. 


Control temperature 


5. 


Accept input from operator's console 


6. 


Update operator's display 



At any given time, the running task — i.e., the task that has control of the processor 
— is the highest-priority task that is ready to run. The running task will continue to 
run until it either voluntarily surrenders control of the processor or is preempted by 
a newly-readied task of higher priority. When the latter situation occurs, the system 
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must save all relevant information about the preempted task (i.e., perform a 
"context save") so that the task can eventually resume processing as though it were 
never interrupted. 



Communication 

Another requirement for a real-time system is that tasks be able to communicate 
with each other. One task may need to invoke another and/or send it certain in- 
formation. For instance, if the operator in our process control example enters a new 
temperature specification, the console input task must invoke the temperature con- 
trol task, supplying it with the new temperature. The temperature control task, since 
it has a higher priority, will immediately preempt the console input task. RMX/80 
provides for intertask communication by means of the message/exchange facility, 
which is described in the following paragraphs. 

Messages and Exchanges. A message is a collection of data that one task com- 
municates — i.e., "sends" — to another task. An exchange is a location where 
RMX/80 queues a list of tasks waiting for messages or a list of messages waiting to 
be received by tasks. 

To avoid the overhead required to move an entire message to an exchange when it is 
sent, RMX/80 merely posts the address of the message. When a message arrives at 
an exchange where tasks are waiting, it is matched with the first waiting task on the 
list, and that task is removed from the list. Likewise, when a task arrives at an ex- 
change where messages are waiting, it is matched with the first waiting message, and 
that message is removed from the list. Task-message communication at an exchange 
is thus first-in/first-out. When a task and a message are matched at an exchange, the 
task is also made ready for execution. 

Note that, as would be expected from the preceding explanation, tasks and messages 
can never be queued at an exchange at the same time. Also note that a task cannot 
wait at more than one exchange at a time. This is true because of the way tasks and 
messages are queued at exchanges, as discussed under "Details of System Opera- 
tion" in Chapter 2. 

A special set of interrupt exchanges is reserved for use with the hardware interrupt 
levels (or the software pseudo-interrupt levels on the iSBC 80/10). These differ from 
the other exchanges in certain ways, which will be discussed more fully in Chapter 2. 

Message-Consuming and Message-Producing Tasks. Most tasks can be classified 
as message-consuming or message-producing tasks or a combination of the two. The 
processing flow of these types of tasks can be shown as follows: 



TASK ENTRY POINT 



TASK ENTRY POINT 



INITIALIZE TASK 



INITIALIZE TASK 



WAIT FOR MESSAGE 



PERFORM FUNCTION 



PERFORM FUNCTION 



INITIALIZE OPERATION 
(SEND MESSAGE) 



SEND RESPONSE 



WAIT FOR RESPONSE 



Figure 1 -2. Schematic of Message-Consuming and Message-Producing Tasks 



RMX/80 



Overview 



A message-consuming task waits for a message to be posted at a particular exchange 
and takes control of the processor only when it has received a message. The message- 
consuming task performs some action based upon the message and then simply 
resumes waiting until the next message is received. Usually, the message-consuming 
task acknowledges completion of its function by returning the message to an ex- 
change where the sending task is waiting for a response. 

A message-producing task initiates its function by sending a message and then sur- 
renders control of the processor. The task continues to wait until it receives a 
response to its message. 

Notice that the distinction between these types of tasks is not absolute, since most 
tasks both produce and consume messages. However, the producer-consumer con- 
cept helps clarify the general structure of tasks. Also note that because communica- 
tion via an exchange implies a first-in/first-out queue of messages, buffering of the 
input data to a consumer task is accomplished automatically. (The message queue 
serves as a buffer.) Thus, a high-priority producer task can be allowed to temporari- 
ly "get ahead" of a low-priority consumer task without loss of data. 



Task States. Thus far, it has been implied that tasks may be in one of two states: 
running or waiting. In addition to these states, a task may also be ready or suspend- 
ed. For convenience, all four task states ar; defined here. 

The running task is the task currently in operation. 

A ready task is one that is ready to run. Any wait for a message or time delay has 
been satisfied. The running task is always the ready task with the highest current 
priority. 

A waiting task is a task that is waiting at an exchange. 

A suspended task is one that is needed within the system, but that the user wishes to 
prevent from competing for system resources. This occurs most commonly during 
testing and debugging. Suspending individual tasks simplifies the real-time environ- 
ment and allows you to concentrate on the portion of the system being tested. 
Another possible reason for suspending a task is that it is no longer needed. For ex- 
ample, a task that performs initialization functions might suspend itself when it has 
finished its processing. 

The RMX/80 software maintains a variety of control structures that keep track of 
all the tasks in the system. Figure 1-3 illustrates the various task states and their in- 
teraction. 
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Figure 1-3. Task 
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The Ready List is the list of all the ready tasks in the system. The Delay List is the 
list of all tasks currently in a timed wait (waits may be timed or unconditional); and 
the Suspend List is the list of all suspended tasks. 

Tasks are always entered on the Ready List in order of priority. The running task is 
always the highest priority task on the Ready List. When several tasks have the same 
priority, they are entered on the Ready List in a first-in/first-out sequence. Tasks 
can be entered on the Ready List for any of three reasons: 

• A task is ready for execution when it is first created. Tasks are created either 
during system initialization or by other tasks at run time. 

• A task becomes ready when a condition for which it has been waiting has been 
satisfied. A task may wait for a message at an exchange or may wait for some 
specific time interval to pass or both. 

• A suspended task becomes ready when it is allowed to resume competition for 
system resources. A task on the Suspend List that is resumed is entered directly 
on the Ready List. 

A task is added to the Delay List when it requests a timed wait. Tasks are entered on 
the Delay List in order of increasing time remaining to satisfy the delay request. (The 
first task on the list has the least remaining time.) A task is removed from the Delay 
List when it "times out," or when a message arrives at the exchange at which the 
task is waiting, whichever occurs first. 

A task is added to the Suspend List if it is ordered suspended by another task or if it 
suspends itself. The Suspend List is not ordered. If a waiting task is ordered 
suspended, RMX/80 waits for the task to become ready before moving it to the Sus- 
pend List. A task on the Suspend List that is resumed is entered directly on the 
Ready List. 



Real-Time Programming for an RMX/80 Application 

Programming for the real-time environment involves certain techniques, some of 
which may not be familiar to the applications programmer. This section introduces 
those aspects of programming which are peculiar to real-time systems as im- 
plemented with RMX/80 software. The details needed for actual programming are 
supplied in Chapters 2 and 3. 

Perhaps the most important real-time programming technique is the dividing of an 
application into tasks. Users who are accustomed to modular programming will find 
the transition to tasking relatively natural and simple. Users who are accustomed to 
writing a single, large program for applications should familiarize themselves with 
modular programming by reading the appropriate sections of the PL/M-80 Pro- 
gramming Manual, 9800268, and the 8080/8085 Assembly Language Programming 
Manual, 9800301. Many references on the subject of modular programming are 
available commercially. 

User tasks must be coded using an RMX/80-compatible Intel language translator. It 
is assumed that the programmer is familiar with the language he is using; language 
details are supplied in the appropriate programming, language reference, and/or 
ISIS-II translator manuals listed in the Preface to this manual. Examples in this 
manual are presented for the most part in PL/M, and in some cases also in 
8080/8085 assembly language. Sufficient information is given in this manual to 
enable programmers to code application tasks and the configuration module in 
either PL/M or assembly language. 
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Identifying Tasks 

One of the real-time programmer's first jobs is to break down his application into 
tasks. As described under "Concurrency" earlier in this chapter, tasks are units of 
processing that can be run concurrently, and which are scheduled for execution by 
the RMX/80 software. Careful identification of tasks is critical to the performance 
of an RMX/80 application system. 



Identifying tasks is basically a matter of subdividing a large application into a series 
of smaller, logically independent programs. Frequently, input/output requirements 
define tasks. In our sample process control application, the temperature and roller 
pressure monitors and the console input a nd output tasks are all directly associated 
with input and output. The temperature and roller control tasks perform some 
calculations and then output the results to the appropriate device. 



In general, it is better to have a number of smaller tasks rather than a few very large 
tasks. However, the number of tasks should not be too great, either. Too many tasks 
add needless complication to the system, making it difficult to modify or debug, and 
also add to system overhead. 



Using Basic RMX/80 Nucleus Operations 

The RMX/80 Nucleus provides a set of primitive operations to facilitate program- 
ming of real-time tasks. The programmer must become familiar with the use of these 
operations, of which the two most important — RQWAIT (Wait for Message) and 
RQSEND (Send Message) — are described briefly here. (Refer to Chapter 2 for com- 
plete definitions of all Nucleus operations and instructions for their use.) 

The RQWAIT Operation. Issuing an RQWAIT (Wait for Message) causes the call- 
ing task to wait for a message at an exchange or (optionally) for a specified time in- 
terval to elapse. The operation requires two parameters, an exchange address and a 
number of system time units; the latter may be zero, indicating an indefinite wait. 
When the task receives a message, RQWAIT returns the address of the message. If a 
time limit is specified and no message becomes available at the exchange before the 
time limit expires, the operation returns (he address of a system message that iden- 
tifies the time- out condition. The timing feature enables the programmer to ensure 
that a task will not wait at an exchange for longer than a specified amount of time. 
Conversely, precise timing intervals can be obtained by performing a timed wait at 
an exchange to which no messages are sen :. 



As an example, consider an output display task that must wait for a message. Ex- 
changes are defined by the user, and are normally addressed symbolically; for in- 
stance, we might use the name DISPEX for the exchange in our example. Let PTR 
be the variable into which the returned message address is to be stored. The time 
limit is specified as a number of system time units (50 milliseconds); a one-second 
wait is specified as 20 time units. Thus a call to RQWAIT specifying a wait of one se- 
cond might be programmed as follows: 



PL/M 



8080/8085 Assembly Language 



PTR=RQWAIT(.DISPEX,20); 



LXI 
LXI 
CALL 
SHLD 



B, DISPEX 
D,20 

RQWAIT 
PTR 
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The RQSEND Operation. RQSEND (Send Message) sends a message to an ex- 
change by posting the address of the message at the exchange. The operation re- 
quires two parameters, an exchange address and a message address. 

A call to send a message called TEXT to the output display task just described might 
be programmed as follows: 

PL/M 8080/8085 Assembly Language 

CALL RQSEND(.DISPEX,.TEXT); LXI B.DISPEX 

LXI DJEXT 
CALL RQSEND 

Typically, the exchange is associated with some other task, but it may be used by the 
sending task, allowing a task to send a message to itself. Note that sending a message 
to an exchange where a higher priority task is waiting will cause the sending task to 
be preempted by the receiving task. 




Once a message has been sent to an exchange, the sending task must 
neither send it again nor alter it in any way until it has been processed by 
the receiving task. 

Working With Control Structures 

The RMX/80 software requires certain control information in order to perform its 
operations. This information is provided in RMX/80 control structures located in 
RAM. The most important of these are Task Descriptors, Exchange Descriptors, In- 
terrupt Exchange Descriptors, message headings, and individual task stacks. The 
programmer of an RMX/80 application system needs to understand these control 
structures, since he must initialize some of them and also access them from time to 
time. The following paragraphs supply a brief functional description of the control 
structures; a more complete discussion appears in Chapter 2 under "Details of 
System Operation." 



Task Descriptors. A Task Descriptor is the control structure that identifies a task to 
the system. It indicates the priority and status (ready, preempted, delayed, or 
suspended) of the task, and gives the address of the task's stack area. 

The RMX/80 Nucleus builds the Task Descriptors in user-allocated RAM from in- 
formation you supply when you configure your system, or when your program re- 
quests the creation of tasks at run time. 



Exchange Descriptors and Interrupt Exchange Descriptors. An Exchange 
Descriptor is the physical representation of an exchange in the system. It enables the 
RMX/80 software to keep track of all the tasks waiting at an exchange or all the 
messages available at the exchange. It includes pointers to a list of tasks and a list of 
messages. As messages are posted at the exchange, as tasks arrive to wait at the ex- 
change, and as tasks receive messages, RMX/80 updates these lists. The RMX/80 
software matches tasks and messages on a first-in/first-out basis. If, for example, 
several messages are queued at an exchange, the first task that waits at the exchange 
receives the first message from the queue, and that message is removed. The next 
time this task (or another task) waits at the exchange, it receives the second message 
from the queue. 
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An Interrupt Exchange Descriptor is a special type of Exchange Descriptor, provid- 
ed to support the translation of hardware nterrupts into messages. A separate inter- 
rupt exchange is defined for each interrupt level used in the application system. An 
Interrupt Exchange Descriptor contains a built-in message; a simple Exchange 
Descriptor does not. 



The RMX/80 Nucleus builds Exchange Descriptors and Interrupt Exchange 
Descriptors in user-allocated RAM from information you supply when you con- 
figure your system, or when your program requests the creation of exchanges at run 
time. 

Message Headings. Each message in the system begins with control information 
known as the message heading. It includes a pointer used to link it to other messages 
waiting at an exchange, indicators of length and message type, and (optionally) 
certain exchange address associated with, the message. 

A user task builds messages in some portion of RAM. This area may be dedicated to 
the message, or the task may request a portion of allocated memory from the Free 
Space Manager (see Chapter 5). The latter option is especially useful when tasks are 
sending variable-length messages. A message can have any length consistent with the 
amount of memory in the system. 



Task Stacks. Each task requires its own stack so that RMX/80 can perform a con- 
text save (storing the contents of the registers, flag bytes, and program counter) 
whenever the task is preempted. When the task next enters the running state, the 
RMX/80 software restores the registers and pops the top of the stack into the pro- 
gram counter, so that execution resumes with the instruction that was next to be ex- 
ecuted when the task was interrupted. 

While running, the task may also store data in its stack for its own purposes. This 
data will not be affected by context saves as long as the stack pointer is properly up- 
dated to reflect the existence of the data on the stack. The user must, however, 
allocate sufficient stack space for this data and the space used by CALL instructions 
as well. 

Specifying the System Conf iguratior 

The great degree of flexibility inherent in the RMX/80 software requires that you 
provide certain information to the Nucleus to enable it to initialize the system. After 
defining and coding your own tasks, you specify the configuration of your system by 
means of the Interactive Configuration Utility, which produces a SUBMIT file. You 
then link and locate your application system by SUBMITting this file. 
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CHAPTER 2 
RMX/80 NUCLEUS 



General Description 

The Nucleus is the heart of an RMX/80 application system and is required for all 
systems. To use the Nucleus, you must be familiar with a number of RMX/80's 
basic operating principles, which are described in Chapter 1 of this manual. These 
principles are not repeated in this chapter except as they apply directly to a particular 
operation. Unless you are already familiar with RMX/80, you should read Chapter 
1 before attempting to read this or any subsequent chapter. The RMX/80 Nucleus 
performs the following functions: 

• Initalizes the system 

• Dispatches and synchronizes tasks 

• Supplies timing functions 

• Provides a means for controlling and exchanging data within the system. 

User tasks communicate with the Nucleus by means of a set of RMX/80 operations 
which are defined later in this chapter. 



Use Environment 

The RMX/80 Nucleus and extensions are designed for use with Intel OEM computer 
systems. Special care has been taken to isolate hardware-dependent functions so that 
user tasks will execute on different iSBC systems with no changes except to the 
SUBMIT file produced by the Interactive Configuration Utility. You can make such 
changes by means of that utility. The only exception to this rule is that iSBC 80/ 10 
users do not have exactly the same iRMX 80 command set at their disposal. 

All versions of the RMX/80 Nucleus software are designed to be fully contained on 
the Single Board Computer. All system hardware resources not used by the RMX/80 
Nucleus are available for the user application (user tasks and user-selected RMX/80 
extension tasks). 

RMX/80 cannot, in general, protect itself against bugs in application tasks. One 
reason that this is true is that the RMX/83 data structures are maintained in RAM 
that is accessible to the application programs. An application task that overflows its 
stack or otherwise writes over an RMX/80 data structure may cause the system to 
malfunction in unexpected ways. The RMX/80 Debugger, described in Chapter 6, is 
designed to allow you to identify and correct such problems so that your application 
will be extremely reliable. 



Memory Requirements 

The RMX/80 Nucleus operations are supplied in two portions, a basic set and an op- 
tional set of operations. The optional operations delete, suspend and resume tasks 
and delete exchanges, and will not be needed in many user applications. The more 
frequently used operations are in the basic set. The Nucleus code with the basic set 
of operations is designed to fit into a single 2K ROM. It can be located in RAM, but 
this requires the system to have some means of loading the code into memory, 
such as the ICE-80. The basic Nucleus requires approximately 250 bytes of RAM 



2-1 



for data storage. If used, the optional operations require up to 210 additional bytes 
of storage for code, and they extend the total data storage requirements to approxi- 
mately 300 bytes of RAM. Each optional operation is linked into the system only 
if the operation is called by a user task. 

Adding tasks and exchanges to the system requires additions to the Nucleus beyond 
the code and/or data storage of the task itself. In addition to its own code and data 
storage, each task adds 17 bytes of ROM and 20 bytes of RAM to the system. Also, 
each task must reserve 24 bytes of stack space beyond its own needs to provide the 
Nucleus with space for saving the task's context should it be preempted. 

Each additional exchange adds 2 bytes of ROM space and 10 bytes of RAM. Each 
Interrupt Exchange adds 2 bytes of ROM space and 15 bytes of RAM. 



Hardware Requirements 

iSBC 80/20. On the iSBC 80/20, the RMX/80 Nucleus uses the 8259 Programmable 
Interrupt Controller chip to provide eight priority interrupt levels. The Nucleus 
automatically updates the 8259 interrupt mask to block all interrupts with the same 
or a lower priority than the current interrupt. This also blocks all tasks with a soft- 
ware priority less than or equal to the current task. 

The RMX/80 Nucleus uses Counter of the 8253 Programmable Interval Timer 
chip to drive the system clock. This counter is jumpered directly to the priority 1 in- 
terrupt. Counter is programmed .to provide a timing interrupt every 50 
milliseconds. Notice that tasks with priorities in the range through 32 can block 
timing interrupts if their cumulative execution time exceeds 50 milliseconds. This 
can cause timing inaccuracies. Counter and the priority 1 interrupt are normally 
dedicated to the timing function and are not available for other use. 

Counters 1 and 2 of the 8253 are not used by the RMX/80 Nucleus; however, the 
Terminal Handler uses Counter 2 to generate the baud rate for the 8251 Program- 
mable Communication Interface (USART). Since most application systems will 
probably include the Terminal Handler, only counter 1 of the 8253 is generally 
available for use by application tasks. 



iSBC 80/24 and 80/30. All hardware requirements outlined for the iSBC 80/20 in 
the previous paragraphs apply also to the iSBC 80/24 and 80/30. 

In addition, the iSBC 80/24 and 80/30 versions support the four on-chip interrupts 
provided by the 8085 processor as described under "iSBC 80/24 and 80/30 
Interrupts" later in this chapter. The 80/24 and 80/30 versions of the Nucleus auto- 
matically update the 8259 and 8085 interrupt masks to block all interrupts with the 
same or lower priority than the current interrupt. 

iSBC 80/10A and 80/10B. The iSBC 80/ 10A does not have an 8259 Programmable 
Interrupt Controller or an on-board interval timer, whereas the iSBC 80/ 10B has no 
8259 but does have an on-board interval timer. The single interrupt on the 8080 
processor is translated into eight interrupt levels via software. If an iSBC 80/ 10A 
system requires any timing functions, a timing signal must be derived off-board to 
drive the RMX/80 clock logic. This imposes both hardware and software require- 
ments, as described in Appendix G, "iSBC 80/ 10 Time Base Considerations." 

Interfacing with the Nucleus 

The user has two general interfaces with the RMX/80 Nucleus. First, the user must 
define the system configuration for the Nucleus. This allows the Nucleus to identify 
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and establish control over the various tasks and exchanges used in the system. Se- 
cond, user tasks can request various services from the RMX/80 Nucleus by in- 
cluding calls to RMX/80 operations in the task's code. 

This section briefly explains system configuration (detailed instructions for coding 
the configuration module are given in Chapter 3) and defines the RMX/80 Nucleus 
operations. In addition, four special topics — message coding, priority levels, timing, 
and interrupt handling — are discussed. You must have a solid understanding of 
these topics in order to code your application tasks. 



Configuration 

When you SUBMIT the file that is created by the Interactive Configuration Utility, 
the result is a system configuration comprising the tasks and exchanges you specified 
while configuring. 

A running task can alter the system configuration dynamically by creating or 
deleting tasks and exchanges. Run-time creation of tasks is frequently performed to 
simplify configuration requirements for the user. In fact, most RMX/80 extensions 
use this technique. For example, the Free Space Manager is comprised of a number 
of tasks, but you are required to supply only one Static Task Descriptor. The Free 
Space Manager's code contains the Static Task Descriptors for its other tasks. As a 
part of its initialization, the Free Space Manager generates the Task Descriptors for 
its other tasks, thereby "creating" the tasks. Of course, all the object code for all 
these tasks was previously linked into the system at the same time. The Free Space 
Manager creates tasks at run time only to simplify configuration requirements for 
you. 

Run-time deletion of a task or exchange allows any RAM used by the task or ex- 
change to be reused for some other purpose . 

Nucleus Operations 

Summary. The RMX/80 Nucleus operations are external procedures that may be 
called by your application tasks. Table 2-1 is a summary of all RMX/80 Nucleus 
operations. 

Notice that all the operation names have thv. prefix RQ. This convention is true of all 
public and external symbols defined by RMX/80, so it is simple to avoid conflicts 
between RMX/80-defined and user-defined symbols. 



Table 2-1 . RMX/80 Nucleus Operations 



_ 



NAME 


OPERANDS 


RETURN 
VALUE 


FUNCTION 


RQACPT 


exch-addr 


addr 


Accept a message, if available, from specified 
exchange. Returns message address if 
available, zero otherwise. 


RQCTCK 


none 


none 


Dec 'ement the time counters of all tasks on the 
Delay List, and transfer such tasks to the 
Ready List if their timed wait periods have ex- 
pired. (Provided in iSBC 80/10 versions only.) 
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Table 2-1 . RMX/80 Nucleus Operations (Cont'd.) 



NAME 


OPERANDS 


RETURN 
VALUE 


FUNCTION 


RQCTSK 


STD-addr 


none 


Create task by building new Task Descriptor 
based on specified Static Task Descriptor. 


RQCXCH 


RAM-addr 


none 


Create exchange at specified RAM address. 


RQDLVL 


level 


none 


Disable specified interrupt level. (Has no effect 
in iSBC 80/10 versions.) 


RQDTSK 


TD-addr 


none 


Delete task specified by Task Descriptor. 


RQDXCH 


exch-addr 


byte 


Delete specified exchange. Returns OFFH if 
successful, 00H if task or message is waiting at 
exchange. 


RQELVL 


level 


none 




Initialize message portion of the Interrupt 
Exchange Descriptor associated with the 
specified interrupt level (the first time called 
only), and enable specified interrupt level. (In 
iSBC 80/10 versions has no effect except for the 
initialization.) 


RQENDI 


level 


none 


Signals end-of-interrupt for specified level in 
user-supplied interrupt service routine. Used in 
place of RQISND. (Has no effect in iSBC 80/10 
versions.) 


RQISND 


lED-addr 


none 


Send an interrupt message to the specified 
interrupt exchange. RQISND may be called 
from a user-supplied interrupt service routine/ 


RQRESM 


TD-addr 


none 


Resume a task that has previously been 
suspended. 


RQSEND 


exch-addr, 
msg-addr 


none 


Send the message located at "msg-addr" to 
the exchange specified by "exch-addr." 


RQSETP 


addr, 
level 


none 


Allow the_ single-level iSBC 80/10 to simulate 
one of the 8 interrupt levels of the 80/20 by 
associating the user-supplied routine at 
"addr" with the specified interrupt level. Each 
user routine can then test one or more hard- 
ware devices to determine whether service is 
required. If so, it services the device and 
returns OFFH. If not, the user routine returns 
OOH to RMX/80, which then activates the 
routine with the next lower priority. (Provided 
in iSBC 80/10 versions only.) 


RQSETV 


addr, 
level 


none 


Set interrupt vector. Interrupts at the specified 
level are serviced by the user-supplied routine 
startina at "addr " thu^ bvna^sina RMX/80 in- 
terrupt software. 


RQSUSP 


TD-addr 


none 


Suspend execution of the task specified by the 
Task Descriptor. 


RQWAIT 


exch-addr, 
time-limit 


addr 


Wait at the specified exchange until a message 
is available or time limit expires. Returns 
address of system time-out message or user 
message. 



— 
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Descriptions of Operations. The following descriptions supply all the information 
you need to use the RMX/80 operations in your application tasks. 

Each description provides the format for ihe statement required to call the operation 
in PL/M. In PL/M, operations are coded differently depending upon whether the 
operation returns a value. When no value is returned, the operation is coded as a 
procedure call. When a value is returned, the operation is coded as an assignment 
statement or an argument of an expression (function reference). (The formats given 
here for operations that return a value show an assignment statement; but any of 
these operations may be coded either way.) 

Lower-case items in the formats identify elements to be supplied by the program- 
mer, who will generally wish to supply them in symbolic form. Specific rules for 
coding parameters are given in the descriptions of individual operations. 

In 8080/8085 assembly language, all RMX/80 operations are coded as subroutine 
calls. Before calling an operation, however, the program must place any parameters 
required for the operation in the proper iegisters. The assembly language rules for 
passing parameters to an RMX/80 operation are the same as for passing parameters 
to a PL/M procedure called from an assembly language module. The first parameter 
is passed in the B and C registers if it is an address value, or the C register if it is a 
byte value. The second parameter is passed in the D and E registers if an address 
value, or the E register if a byte value. If the operation returns an address value, it is 
returned in the H and L registers. If the operation returns a byte value, it is returned 
in the accumulator. 

In either language, you must be certain to declare the names of any operations used 
in a task as EXTERNAL. 

The most frequently used RMX/80 operations by far are RQSEND and RQWAIT. 
In fact, a majority of RMX/80 systems will require only these two operations. 
Somewhat more complex systems may also find a need for the RQACPT operation. 
Therefore, these three operations are described first. The remaining operations are 
then described in alphabetical order. 



RQSEND Operation. 

Function. The RQSEND (Send Message I operation queues a message at an ex- 
change. If one or more tasks are waiting at the exchange, the message is given to the 
first waiting task, and the task is made ready. In this case, both the task and the 
message are removed from the exchange. 

Format. 

CALL RQSEND(exchange-address, message-address); 

Description. RQSEND is reentrant and may be called at any time by a running task. 

The RQSEND operation has two parameters. The first specifies the address of the 
exchange to which the message is to be sent. The second specifies the address of the 
message. Notice that sending a message does not imply that the message is actually 
moved. Instead, its address is added to the queue of message addresses at the ex- 
change. 

The sending task must not alter a message after it is sent. Since the message is not ac- 
tually moved, it is in fact still accessible to the sending task. However, altering the 
message after it has been sent subverts the purpose of sending it to another task. 
This raises the question of how the sending task knows when it can reuse the RAM 



to build a new message. Typically, the receiving task returns a response message to 
tell the sending task that the message has been processed. Note that the response 
message should be returned via a separate exchange. Frequently, the original 
message is returned as a response, possibly with updated status information or 
return values. 

A task effectively preempts itself by sending a message to an exchange where a 
higher-priority task is waiting. The waiting task is readied upon receipt of the 
message. Since the receiving task has the higher priority, it becomes the running 
task. The sending task is preempted, but remains ready to run. Conversely, a task 
can send any number of messages to lower-priority tasks without being preempted — 
unless, of course, an interrupt occurs for a higher-priority task. 

If a task is waiting in a timed delay when a message is received at its exchange, the 
delay is cancelled, and the task is made ready. 

Because of the way RMX/80 messages and exchanges are structured, a message con- 
not be sent to more than one exchange at a time. 



RQWAIT Operation. 

Function. RQWAIT (Wait for Message) returns the address of a message to the call- 
ing task. The calling task waits at an exchange until a message has been received or 
until a specific amount of time has elapsed. If a message is received, RQWAIT 
returns the address of that message. If the time limit elapses before a message is 
received, the address returned to the calling program is the address of a system time 
out message (a 5-byte message with type TIME$OUT$TYPE=3; see Appendix C). 

Format. 

message-address=RQWAIT(exchange-address, time-limit); 

Description. RQWAIT is reentrant and may be called at any time by a running task. 
Maximum time limit is FFFEH, or 65,534, system time units; i.e., a time limit of 
65,535 or more system time units is not permitted. 

The RQWAIT operation has two parameters. The first parameter specifies the ad- 
dress of the exchange where the task is to wait. The second specifies the time limit of 
the wait. A time limit value of zero indicates no time limit; i.e., the task will wait in- 
definitely. An RQWAIT operation with no time limit incurs less system overhead 
than a timed RQWAIT. 

The optional time limit is specified as a number of system time units (one system time 
unit is 50 msec for the 80/20, 80/24, or 80/30 versions). A one-second wait (for the 
80/20, 80/24, or 80/30) is specified as 20 time units. Notice that the duration of the 
first time unit is usually unpredictable. Your task may enter the wait immediately 
after a clock tick (50 msec timer interrupt). In this case, the duration of the first time 
unit (for the 80/20, 80/24 or 80/30) is very nearly a full 50 msec. On the other hand, 
your task may enter the wait an instant before a clock tick. In this case, the duration 
of the time unit may be nearer one millisecond. After the first clock tick, the wait 
becomes synchronized with the clock; all subsequent time units are a full 50 msec. 

If you are using an iSBC 80/10-based system and you need timed RQWAIT opera- 
tions, you must provide an off-board clock in your hardware configuration. Also 
note that consequently, the length of a system time unit in your 80/10 system may be 
other than 50 milliseconds. (See Appendix G for a discussion of timing for the iSBC 
80/10.) 
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The exchange address parameter may be specified as zero. In this case, a default ex- 
change address is taken from the calling task's Task Descriptor. The default ex- 
change address may be specified in the Static Task Descriptor when the system is 
configured; this address is placed in the Task Descriptor at initialization. However, 
RMX/80 updates the exchange address of the Task Descriptor each time it en- 
counters a RQWAIT or RQACPT operation with a non-zero exchange address. 
Therefore, the default exchange address in the Task Descriptor can be either the ex- 
change address specified in the Static Task Descriptor or the address of the exchange 
where the task waited last. 

If a message is already waiting at the exchange when the task executes the RQWAIT, 
the first message is removed from the Exchange Descriptor's queues, and the task re- 
mains on the Ready List. Unless an interrupt causes a higher-priority task to become 
ready, the calling task remains the running task. 

If no message is waiting at the exchange, the calling task is removed from the list of 
ready tasks and added to the queue of tas ts at the exchange. When a non-zero time 
limit is specified for the RQWAIT, the task is also queued on the Delay List. The 
task continues to wait at the exchange until it receives a message or until the 
specified time limit elapses. At this point, the task is again made ready and removed 
from the Delay List. 

If the time limit expires before a message arrives at the exchange, RMX/80 passes 
the address of a system message to the task and readies it. The TYPE field of this 
message always contains 3H so the task can determine if it timed out. 

Because of the way RMX/80 tasks and exchanges are structured, a task cannot wait 
at more than one exchange at a time. 

RQACPT Operation. 

Function. RQACPT (Accept Message) returns either the address of a message or 
zero to the calling task. The calling task does not have the option of waiting. A 
message address is returned if a message is available at the specified exchange; zero is 
returned if no message is available. 

Format. 

message-address=RQACPT(exchange-address); 
Description. RQACPT is reentrant and may be called at any time by a running task. 

RQACPT has one parameter, the exchange address from which the task will accept 
a message, if one is available. The exchange address may be specified as zero. In this 
case, a default exchange address is taken f rom the task's Task Descriptor. This ad- 
dress is either the address of the exchange from which the task last took a message, 
or (if the task has received no messages since the system was last restarted) the 
default exchange address specif ied in the Static Task Descriptor. 

RQACPT is useful when a task must handle messages from a number of different 
exchanges. As explained in the description of RQWAIT, a task can wait at only one 
exchange at a time. Furthermore, if a task attempts to wait sequentially at several ex- 
changes, it may wait forever at one exchange even though a message is available at 
another exchange. In some cases the RQACPT operation can be used to overcome 
this problem, since it does not require the task to wait. 



2-7 



Nucleus 



RMX/80 



Executing a series of RQWAIT operations with a time limit of one time unit is ap- 
proximately equivalent to executing a series of RQACPT operations, but the system 
overhead is slightly greater when the RQWAIT operations are used. It should be 
noted, however, that a task that loops through a series of RQACPTS prevents lower 
priority tasks from running. 

Care must be taken when using the default exchange address in a task that uses both 
RQWAIT and RQACPT operations. Both of these operations modify the exchange 
address stored in the Task Descriptor for that task. Unless care is taken, the task 
could end up trying to accept and wait for messages at the same exchange. 

If no message is currently available at the specified exchange, RQACPT returns zero 
to the calling task. The task should, of course, test for this condition. 



RQCTCK Operation. 

Function. RQCTCK (Clock Tick) decrements the time counters of all tasks on the 
Delay List each time another system time unit has passed, and transfers such tasks to 
the Ready List when their timed wait periods have expired. The RQCTCK operation 
is defined only for the iSBC 80/ 10 versions; it's function is performed automatically 
in the iSBC 80/20, 80/24 and 80/30 versions. 

Format. 

CALL RQCTCK; 

Description. The RQCTCK procedure is not reentrant and therefore must only be 
called by one task at a time. 

RQCTCK must be called by the polling routine that services the interrupt from the 
clock hardware. The user-supplied variable RQTCNT (tick count) is used to deter- 
mine the number of clock interrupts that correspond to a system time unit. If you do 
not set this variable, RQTCNT assumes a default value of 50. This provides a system 
time unit of 50 msec if the clock interrupt occurs once each millisecond. 

For additional information concerning iSBC 80/10 timing routines, see Appendix 
G. 



RQCTSK Operation. 

Function. RQCTSK (Create Task) identifies a task to RMX/80, initializes it, and 
makes it ready for execution. 

Format. 

CALL RQCTSK (Static Task Descriptor-address); 

Description. RQCTSK is reentrant and may be called at any time by a running task . 

RQCTSK has one parameter. This parameter must be the address of a Static Task 
Descriptor. The Static Task Descriptor may be in either ROM or RAM, but is nor- 
mally in ROM. RQCTSK uses the information in the Static Task Descriptor to build 
a Task Descriptor in RAM. After the Task Descriptor is built, RQCTSK makes the 
task ready and inserts it in the Ready List according to its priority. 
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RQCTSK also initializes the newly created task's stack by filling the entire stack area 
with the value UNUSED FLAG (0C7H) This flag can be useful when testing a 
system. The absence of the flag indicates that the stack area has either been com- 
pletely filled or has overflowed. A large r.umber of flags in the stack area may in- 
dicate that the stack is excessively large anc can be reduced. 

As mentioned earlier, creating a task dynamically implies that the code for that task 
is already in memory or can somehow be placed into memory. 



RQCXCH Operation. 

Function. RQCXCH (Create Exchange) identifies and initializes an exchange for 
RMX/80. 



CALL RQCXCH (exchange-address); 

Description. RQCXCH is reentrant and may be called at any time by a running 
task. 

RQCXCH has one parameter. This parameter must be the address of ten bytes of 
contiguous RAM where RMX/80 is to build a new Exchange Descriptor. 

The RMX/80 Nucleus uses RQCXCH to build and initialize the exchanges specified 
for the system configuration in the Create Table. However, user tasks can also call 
RQCXCH, if desired. In this case you muse be certain to create the exchange before 
any other task attempts to send a message to, or wait at, the exchange. 

The Create Table must specify at least one Static Task Descriptor, but it may specify 
zero exchanges. In this case, the user must be certain to build at least one Interrupt 
Exchange Descriptor before the system falls into the idle task. The idle task puts the 
processor into a HALT. The only way to get out of a HALT (short of a system 
RESET) is by honoring an external interrupt. To create an Interrupt Exchange 
Descriptor, you must call RQCXCH (to initialize the first ten bytes), then RQELVL 
(to initialize the last five bytes). 



RQDLVL Operation. 

Function. RQDLVL (Disable Level) disabl ;s the specified interrupt level by modi- 
fying an internal system mask. The disable takes effect immediately. 



CALL RQDLVL(level); 

Description. RQDLVL is reentrant and may be called at any time by a running task. 

The operation has one parameter, the interrupt level to be disabled. Because only one 
level may be specified, you must call RQDLVL once for each interrupt level to be 
disabled. Permissible values of "level" for the iSBC 80/20 and 80/ 10 versions are 0-7; 
for the iSBC 80/24 and 80/30 versions, 0-7 or 9=A$LEV, 10=B$LEV, or 
ll=C$LEV. (ASLEV, BSLEV, and CSLEV correspond to the 8085 on-chip 
interrupts RST 7.5, RST 6.5, and RST 5 5 respectively.) Since the 8085 TRAP 
interrupt cannot be masked or unmasked, a call to RQDLVL for 8=TRAP has no 
effect. 



Format. 



Format. 
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Because interrupt levels in the iSBC 80/ 10 version are actually created by software 
from one hardware interrupt, it is not possible to selectively mask off specific inter- 
rupt levels with the iSBC 80/ 10. For this reason, RQDLVL has no effect in the 80/10 
versions of RMX/80. The 80/10 versions of RMX/80 follow the convention of dis- 
abling all eight interrupts whenever the running task has a priority from to 128, and 
enabling all levels when the running task's priority is from 129 to 255. 

Disabling an interrupt level that is already disabled has no effect. 



RQDTSK Operation. 

Function. RQDTSK (Delete Task) removes the specified task from the Task List 
and any other list in which it appears. 

Format. 

CALL RQDTSK (Task Descriptor-address); 

Description. RQDTSK is reentrant and may be called at any time by a running 
task. 

RQDTSK has one parameter which must specify the address of the Task Descriptor 
of the task to be deleted. 

If the deleted task is also the running task, RMX/80 starts execution of the current 
highest priority ready task upon completion of the RQDTSK operation. 

Deleting a task frees up the memory required for its Task Descriptor and stack. You 
can re-use this memory for other purposes, if desired. 

Note that a task may delete itself by executing a call to RQDTSK with the parameter 
RQACTV. (RQACTV is an RMX/80-defined PUBLIC variable which contains the 
Task Descriptor address of the running task.) 

RQDTSK is an optional Nucleus operation; it is linked into a system only if it is call- 
ed by a user task or specified explicitly in the LINK command. 



RQDXCH Operation. 

Function. RQDXCH (Delete Exchange) deletes the specified Exchange Descriptor. 
If the exchange is still in use, as indicated by the presence of either a message or task 
waiting at the exchange, it cannot be deleted; the value returned indicates whether 
the deletion is accomplished. 

Format. 

byte-variable=RQDXCH (exchange-address); 

Description. RQDXCH is reentrant and may be called at any time by a running 
task. 

You must be certain that an exchange is no longer of any use in the system before 
deleting it. 

RQDXCH has one parameter which specifies the address of the Exchange Descrip- 
tor to be deleted. 
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RQDXCH returns a one-byte Boolean (t: ue or false) value to indicate whether the 
deletion has succeeded. A returned value of OFFH indicates that the Exchange 
Descriptor has been deleted. All zeros indicate failure. The deletion fails if there is a 
task or message queued at the exchange. 

RQDXCH is an optional Nucleus operation; it is linked into a system only if it is 
called by a user task or specified explicitly in the LINK command. 



RQELVL Operation. 

Function. RQELVL (Enable Level) enables the specified interrupt level by modify- 
ing an internal system mask. The enable takes effect immediately. The first time 
RQELVL is called, it also initializes the message portion of the Interrupt Exchange 
Descriptor associated with this interrupt level. 

Format. 

CALL RQELVL(level); 

Description. RQELVL is reentrant and may be called at any time from a running 
task. 

The operation has one parameter, which must specify the interrupt level to be 
enabled. Because only one level may be s aerified, you must call RQELVL once for 
each interrupt level to be enabled. Permissible values of "level" for the iSBC 80/20 
and 80/10 versions are 0-7; for the 80/24 and 80/30 versions, 0-7 or 9=A$LEV, 
10=B$LEV, or 11=C$LEV. (ASLEV, B$LEV, and C$LEV correspond to the 8085 
on-chip interrupts RST 7.5, RST 6.5, and RST 5.5, respectively.) Since the 8085 
TRAP interrupt cannot be masked off, ard since no Interrupt Exchange Descriptor 
is defined for TRAP, a call to RQELVL for 8=TRAP has no effect. 

Enabling an interrupt level does not override the software priority scheme. The in- 
terrupt will still be blocked if the running task has a priority higher than or equal to 
the priorities associated with the enabled level. 

Since the iSBC 80/ 10 interrupt levels are created by software from a single hardware 
interrupt, specific numbered levels cannot be masked off in the 80/10 versions. The 
RQELVL operation has no effect on hardware on either of the 80/ 10's. RMX/80 
follows the convention of disabling all eij'ht interrupt levels whenever the running 
task has a priority from to 128, and enabling all levels when the running task's 
priority is from 129 to 255. However, in an iSBC 80/ 10 system RQELVL must still be 
called to initialize the message portion of the Interrupt Exchange Descriptor for that 
level. This must be done after the call to RQSETP for the same level. 

Enabling an interrupt level that is already enabled has no effect. 



RQENDI Operation. 

Function. RQENDI (End Interrupt) is to be used only in user-supplied interrupt 
routines. The operation informs RMX/80 that the user routine has completed the 
interrupt operation at the specified level; this allows RMX/80 to perform the 
appropriate hardware functions required to acknowledge the interrupt. The exact 
functions performed depend on which Single Board Computer is being used. 
RQENDI is meaningless (i.e., a null procedure) in the iSBC 80/10 versions. 

Format. 

CALL RQENDI (level); 
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Description. No parameters are required with the RQENDI operation, and 
RQENDI does not return any value. 

Because RQENDI is used only in user-supplied interrupt service routines, it must be 
used in conjunction with an RQSETV (iSBC, 80/20, 80/24, and 80/30) operation. 
(Refer to the descriptions of these operations, and to the "Interrupt Handling" 
section later in this chapter, for further information.) User-supplied interrupt service 
routines operate completely outside the RMX/80 task framework. The only opera- 
tions that may be called from such a routine are RQENDI and RQISND. Note that 
both of these routines must be called with interrupt disabled. 



RQISND Operation. 



Function. RQISND (Interrupt Send) is to be used only in user-supplied interrupt 
service routines. The RQISND operation sends a message to an interrupt exchange. 
RQISND also informs RMX/80 that the user routine has completed an interrupt 
operation; this allows RMX/80 to perform the appropriate hardware functions re- 
quired to acknowledge the interrupt. The exact functions performed depend on 
which Single Board Computer is being used. 

Format. 



CALL RQISND(Interrupt Exchange Descriptor-address); 

Description. RQISND is not reentrant and must be called only when interrupts are 
disabled. As long as RQISND is called only from user-supplied interrupt service 
routines entered via an RQSETV or RQSETP operation, these requirements are met 
implicitly. Interrupts are disabled when a user-supplied interrupt service routine is 
entered, and are not enabled again until just before the routine executes the RET 
(return) instruction. 

RQISND has one parameter, which must be the address of an Interrupt Exchange 
Descriptor. 

Because RQISND is used only in user-supplied interrupt service routines, it must be 
used in conjunction with either an RQSETV (iSBC 80/20, 80/24 and 80/30) or 
RQSETP (iSBC 80/ 10A and 80/ 10B) operation. (Refer to the descriptions of these 
operations, and to the "Interrupt Handling" section later in this chapter, for further 
information.) User-supplied interrupt service routines operate completely outside the 
RMX/80 task framework. The only operations that may be called from such a 
routine are RQISND and RQENDI. 

RQRESM Operation. 

Function. RQRESM (Resume Task) allows a previously suspended task to compete 
once again for system resources. If the specified task is on the Suspend List, 
RMX/80 enters the task on the Ready List according to its priority. If this makes it 
the highest priority task in the system, it becomes the running task. 

Format. 

CALL RQRESM(Task Descriptor-address); 

Description. RQRESM is reentrant and can be called at any time by a running task. 

RQRESM has a single parameter which must specify the address of the Task 
Descriptor for the task that is to be resumed. 
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RQRESM clears the suspended flag in the STATUS field of the Task Descriptor. 
Clearing this flag for a task that is not currently suspended has no effect. 

The RQRESM and RQSUSP (Suspend Task) operations are provided mainly for 
debugging purposes. They are optional operations that are linked into the system 
only if called by a task. If your system docs not call one of these operations but you 
wish to use the operation for debugging, you must link it in separately, as described 
under "Linking and Locating" in Chapter 3. 



RQSETP Operation. 

Function. By associating a user-supplied interrupt polling routine with an interrupt 
level number, RQSETP (Set Poll) enables the iSBC 80/ 10A and 80/ 10B to simulate 
the eight interrupt levels of the iSBC 80/20. The RQSETP operation is defined only 
for the iSBC 80/10 versions. 

Format. 

CALL RQSETP(procedure-address, level-number); 

Description. All interrupts on the iSBC 80/ 10A and 80/ 10B are received through 
hardware interrupt level 7. RQSETP allows the user to define software pseudo- 
interrupt levels through 7, where is the highest. When an interrupt is received, 
RMX/80 automatically calls the set of user-supplied interrupt polling routines one at 
a time, starting with level and continuing through level 7. Thus, the system polls up 
to eight possible levels of interrupts. The user must supply an interrupt handling 
routine for each RQSETP operation. 

It is not necessary to supply polling routines for unused interrupt levels, since 
RMX/80 supplies default routines in UNRSLV.LIB. (These are null procedures.) 
The compiler warning messages generated when these routines are not declared may 
be ignored. However, you may wish to declare polling routines for the unused levels 
in order to avoid the warning messages. 

User routines named in RQSETP operations have a unique status. They are not 
tasks, but procedures or subroutines. Nor do they operate completely outside the 
RMX/80 software framework. These routines are invoked by the RMX/80 polling 
software, which calls the routines in order by their associated interrupt levels. 

When an interrupt occurs, control passes to an RMX/80 routine that controls the 
order in which the user-supplied polling routines are executed. This RMX/80 
routine performs a context save, but does not supply a stack for the user polling 
routine. Therefore, the user-supplied routines share the stack of the task executing 
when the interrupt occurs. Since interrupts cannot be predicted, each task must in- 
clude enough additional stack space to accommodate its own needs and the needs of 
the interrupt polling routines. Rather than impose this burden on all tasks, the user 
can reserve a block of RAM as the stack For the polling routines. When invoked, 
each polling routine can save the current Stack Pointer and substitute its own. The 
user routine must restore the Stack Pointer before returning to the RMX/80 polling 
controller or calling RQISND. This technique is not required if the user-supplied 
routine pushes no data on the stack and calls no procedure other than RQISND. 

Each user-supplied polling routine must inform the RMX/80 Nucleus whether it 
assumes responsibility for the interrupt that has occurred. It does this by returning a 
value to RMX/80. For PL/M programmeis, user-supplied interrupts are byte-type 
procedures. The procedure must return a TRUE value (0FFH) if it accepts respon- 
sibility for the interrupt; the procedure returns FALSE (00H) if it does not accept 
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responsibility for the interrupt. For assembly-language programmers, these inter- 
rupt routines are subroutines called by RMX/80. Before executing a return instruc- 
tion, the subroutine must place either OFFH or 00H in the accumulator. 

For additional information concerning interrupts, see "Interrupt Handling" later in 
this chapter. 



RQSETV Operation. 

Function. RQSETV (Set Interrupt Vector) allows the user to bypass the normal 
RMX/80 interrupt handling software and process interrupts directly. Although 
RQSETV is permitted for any version of the RMX/80 Nucleus, it is intended 
primarily for the iSBC 80/20, 80/24 or 80/30. Using this operation with the iSBC 
80/10 versions causes the software interrupt polling scheme to become inoperative, 
rendering the RQSETP operation meaningless. 

Format. 

CALL RQSETV(procedure-address, level); 

Description. RMX/80 normally vectors (directs) interrupts to its own interrupt 
handlers. These typically cause a context switch to a user task waiting at an interrupt 
exchange. In some cases this may not be fast enough to service high-speed inter- 
rupts. RQSETV allows the user to direct interrupts to his own interrupt routine 
rather than to RMX/80. 

RQSETV requires two parameters. The first parameter must specify the address of 
the user-supplied interrupt routine. The second parameter specifies the interrupt level 
for which the user supplies his own software. Permissible values of "level" for the 
iSBC 80/20 version are 0-7; for the iSBC 80/ 10s, level 7; for the iSBC 80/24 and 
80/30, 0-7 or 8=TRAP, 9=A$LEV, 10=B$LEV, or 11=C$LEV. (TRAP, ASLEV, 
BSLEV, and CSLEV correspond to the 8085 on-chip interrupts TRAP, RST 7.5, 
RST 6.5, and RST 5.5, respectively.) 

The user-supplied interrupt routine operates outside the task framework provided 
by RMX/80. Control passes directly to the user-supplied routine; no context save is 
performed. In effect, the user-supplied routine just rides on top of the task executing 
when the interrupt occurs. Therefore, the user-supplied routine must save and 
restore any registers it uses. Notice that the user-supplied routine does not have its 
own stack and therefore shares the stack that was in use when the interrupt oc- 
curred. Since the occurrence of an interrupt cannot be predicted, each task must in- 
clude enough additional stack space to accommodate its own needs and the needs of 
the interrupt routine. Rather than impose this burden on all tasks, the user pro- 
ced ure can reserve RAM for its own stack. When invoked, the procedure can save 
the current Stack Pointer and substitute its own. The procedure must restore the 
Stack Pointer before it returns to the interrupted task or calls RQISND. Allocating a 
separate stack is not necessary if the procedure does not push anything on the stack 
and does not call any procedures other than RQISND and RQENDI. 

Note that if the interrupt procedure is coded as a PL/M procedure with the INTER- 
RUPT attribute, the primary control SNOINTVECTOR must be specified at the 
beginning of the module in which it is contained. This is necessary to prevent the 
compiler from attempting to write a restart vector over ROM used by RMX/80 
code. 

RQSETV is provided because RMX/80 imposes a certain amount of overhead when 
it services interrupts. In addition to performing a context save, RMX/80 also up- 
dates several of its control structures. The user may be able to bypass some of the 
overhead by supplying his own interrupt handling routing entered via RQSETV. For 
an example, see "User-Supplied Interrupt Routines" later in this chapter. 
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Most applications require only one RQSETV operation in the system for each level 
of interrupt for which the user supplies an interrupt routine. It is possible, however, 
to change peripheral devices while the system is running. In this case, RQSETV 
might be used to change the interrupt handling to service different devices using the 
same Interrupt Exchange Descriptor. Nole that one cannot reset the interrupt vec- 
tors to the standard system interrupt service routines once they have been redirected 
with RQSETV. 

For additional information concerning interrupts, refer to "Interrupt Handling" 
later in this chapter. 



RQSUSP Operation. 

Function. RQSUSP (Suspend Task) suspends a task, thus making it unable to com- 
pete for system resources. 

Format. 

CALL RQSUSP (Task Descriptor-address); 

Description. RQSUSP is reentrant and ma y be called at any time by a running task . 

RQSUSP has one parameter which must specify the address of the Task Descriptor 
for the task that is to be suspended. 

RQSUSP alters the STATUS field of the Task Descriptor to indicate that the task is 
suspended. Subsequent actions depend on whether the specified task is running, 
ready, or waiting: 

• A running task may suspend itself. The running task surrenders control of the 
processor, and its Task Descriptor is placed on the Suspend List. Control of the 
processor passes to the highest priority ready task. When the suspended task is 
resumed and gains control of the processor, execution resumes at the next in- 
struction after the call for RQSUSP. 

• When a ready task is suspended, its STATUS is set to suspended and its Task 
Descriptor is placed on the Suspend List. 

• When a waiting task is suspended, its STATUS is set to suspended. However, no 
further action is taken until the task becomes ready. The Task Descriptor is 
placed on the Suspend List when the task becomes ready. This ensures that the 
task is ready to be executed when it is resumed. 

Suspending a task that is already suspended has no effect. 

RQSUSP is not required in most systems, since you can achieve the same effect by 
having the task wait at an exchange. In effect, the task remains suspended until a 
message is sent to that exchange. However, suspending tasks during debugging is 
useful, since it simplifies the system and allows you to concentrate on particular por- 
tions of the system. 

The RQSUSP and RQRESM (resume) operations are provided mainly for de- 
bugging purposes. If your system does not c all one of these operations but you wish 
to use the operation for debugging, you must link it in separately, as described under 
"Linking and Locating" in Chapter 3. 
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General Rules. Before sending a message via the Nucleus operation RQSEND, a 
user task must build the message in RAM. All RMX/80 messages must conform to 
certain structural rules, whether the receiving task is an RMX/80 extension task or a 
user task. These rules are given in the following paragraphs. 

Every message consists of a heading which may be from five to nine bytes long, and 
an optional remainder which may be any length. The generalized format of an 
RMX/80 message is shown in figure 2-1 . RMX/80 supplies the data for the first two 
bytes of the message (the LINK field); the user tasks supply the remaining fields, in- 
cluding the remainder. The remainder and the HOME EXCHANGE and 
RESPONSE EXCHANGE fields are optional, in that they are not required in all 
messages; however, certain RMX/80 extension tasks receive user messages that must 
include one or more of these fields. Note that the optional fields must start at the 
offsets shown in figure 2-1. Therefore, in a message that uses RESPONSE EX- 
CHANGE but not HOME EXCHANGE, RESPONSE EXCHANGE must still be 
located at byte 7. (In this case, the two bytes or "filler" (bytes 5 and 6) could be used 
for any user data.) 

RMX/80 uses the LINK field to link together multiple messages waiting at the same 
exchange. This field should not be changed by user tasks. 

The user task must set the LENGTH field. The value set must be the length in bytes 
of the entire message, including the remainder. 

TYPE is a one-byte field whose meaning is defined by the user or by RMX/80. Type 
numbers through 63 are reserved for RMX/80-defined message types. Some of 
these message types are used internally by the Nucleus, and some communicate in- 
formation to RMX/80 extension tasks. A list of all currently defined RMX/80 
message types is given in Appendix C. (For convenience in PL/M programming, 
RMX/80 supplies INCLUDE files that assign symbolic names to these message 
types. The names of these INCLUDE files are given in Appendix A.) Type numbers 
64 through 255 are available for user- defined message types. 

The HOME EXCHANGE field contains the address of the exchange to which the 
message is to be sent when it has no further use in the system. This field is useful for 
managing pools of messages. 

The RESPONSE EXCHANGE field contains the address of the exchange to which a 
logical response to this message should be sent. This information is often very useful 
to the programmer. Assume, for example, that task A builds a data string and sends 
it to task B for processing, and that task A cannot proceed until the string is pro- 
cessed. Task A can wait at a response exchange immediately after sending a message 
to task B. In turn, task B can send a message to this response exchange when it has 
completed processing the data string. 



MESSAGE 
HEADING 
(BYTES 
THROUGH Bl 



REMAINDER 
(BYTES 9 
THROUGH END 
OF MESSAGE) 



LINK 
LENGTH 



TYPE 



HOME EXCHANGE (OPTIONAL) 



RESPONSE EXCHANGE (OPTIONAL) 



ADDITIONAL DATA 
(OPTION AL;VARIABLE IN LENGTH) 



Figure 2-1. RMX/80 Message Format 
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Messages to RMX/80 Extension Tasks. RMX/80 extension tasks that receive 
messages from user tasks generally have more specific rules for the coding of these 
messages. The chapters on the RMX/80 extension tasks supply format diagrams and 
rules for these particular types of messages. 

In messages used to communicate with extension tasks, some fields may be 
designated as unused. The application task may use these fields for its own pur- 
poses. 



Priority Levels 

As described in Chapter 1, RMX/80 uses a system of priority levels to determine 
scheduling of tasks. You must assign a priority level number to every RMX/80 ex- 
tension task and user task in your application system. 

When a higher-priority task preempts execution of a lower-priority task (either as 
the result of an interrupt or by timing out on a timed wait), RMX/80 saves all rele- 
vant information about the preempted task: (i.e., CPU registers, flag byte, and pro- 
gram counter) on the task's stack so that it can eventually resume execution as 
though it were never interrupted. This process is known as a context save. In con- 
trast, RMX/80 saves only the program counter when a task voluntarily surrenders 
control of the processor. (This occurs when the task sends a message to an exchange 
where a higher-priority task is waiting, or when it waits at an exchange where no 
message is queued.) Then RMX/80 simply begins execution of the task with the 
highest current priority. 

The RMX/80 software provides 256 priority levels. Priority level zero is the highest 
priority; 255 is the lowest priority. It is important to remember that the lower the 
priority level number, the higher the priority. 255 should not be used since it is 
reserved for the idle task. 

There is nothing wrong with assigning two tasks the same priority level; in fact, in 
some cases it may serve a purpose to do so. For instance, it may be advisable to 
assign the Free Space Manager the same priority as some time-critical task that 
depends upon RAM allocations. When two :asks have the same priority, note that it 
cannot be predicted which task will be ahead of the other on the Ready List. 



Priorities Associated with Interrupts. Certain software priorities correspond to 
each of the hardware interrupt levels provided by the iSBC 80/20, 80/24, or 80/30. A 
similar correspondence exists between software interrupt levels on the iSBC 80/10A 
or 80/10B. These correspondences are summarized in table 2-2. 

A task that is to service a particular interrupt level must be assigned a software 
priority in the range associated with that interrupt. For example, if an analog-digital 
interface uses interrupt level 2, the task associated with that interrupt must have a 
software priority in the range from 33 to 48. 



Son-Interrupt Priority Levels. Priority levels 129 through 254 are not associated 
with interrupt levels. These are the levels generally used for non-interrupt-driven 
tasks — i.e., tasks initiated by messages sent from other tasks rather than by inter- 
rupt messages. An example of such a task is a long arithmetic routine that receives 
input from an interrupt-driven task. Such routines should normally be assigned 
lower priority levels (i.e., higher priority level numbers) than the tasks that service 
interrupts. 
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Table 2-2. Correspondence between Interrupt Levels 
and Software Priority Levels 



Software 
Priority 
Level 


iSBC 80/20 Hardware 

Interrupt Level or 
iSBC 80/10 Pseudo- 
Interrupt Level 


iSBC 80/24 or 80/30 
Hardware 
Interrupt Level* 


0" 





A$LEV (level 7.5) 


1-4 





A$LEV (level 7.5) 


5-8 




n 
u 


B$LEV (level 6.5) 


13-16 








17-32 


1 


1 


33-48 


2 


2 


49-64 


3 


3 


65-80 


4 

5 


4 
, 




81-96 


97-112 


6 


6 


113-128 


7 


7 


129-254 


None 


None 



Note: The TRAP interrupt level on the 8085 processor cannot be masked off, and 
therefore transcends the RMX/80 priority scheme. 

Software priority level is used by the RMX/80 Debugger for the scan and exchange 
breakpoint facilities. If you plan to use these facilities, you must avoid assigning any 
task a priority level of 0. 



The Idle Task. Priority level 255 is reserved for the idle task, which is invoked by 
RMX/80 when no other task in the system has a need for the processor. The idle 
task puts the processor in the HALT state until it receives an external interrupt. 
Because no instructions are fetched during a HALT, the system bus is freed for more 
efficient direct-memory-access data transfers. 

Timing 

The one facility for clock timing in an RMX/80 system is the timed RQWAIT opera- 
tion. Its purpose is to allow the programmer, if he so desires, to ensure that a task will 
not wait at an exchange for longer than a specified length of time. The minimum 
interval of real time recognized by the system is a system time unit, which you specify 
(within your board's limits) during configuration. (In the iSBC 80/ 10 version the 
length of a system time unit may have some other value, as discussed in Appendix G. 
Using 50 milliseconds is recommended, however, so that tasks can run on alternate 
systems.) 

It is important to note that although the system clock (Counter of the Intel 8253 
Programmable Interval Timer chip on the iSBC 80/20, 80/24, or 80/30, or a user- 
supplied clock for the iSBC 80/ 10) may operate continuously, the clock ticks (clock 
interrupts) are recognized by RMX/80 only during those periods when at least one 
task in the system is waiting with a time delay. When no task is in a timed wait (i.e., 
when the Delay List is empty), the clock is "turned off as far as RMX/80 is con- 
cerned, in order to save the system overhead time required to recognize the clock 
interrupts. If you wish to keep continuous track of time in your system, you must 
program your tasks so that one task is always in a timed wait when the clock ticks. 
Appendix J provides an example of a system programmed in this way. 

Note also that, as explained in the description of the RQWAIT operation, the dura- 
tion of the first time unit in a delay is usually unpredictable. This is because the task 
may enter the waiting state at any time between one clock tick and the next. 
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The iSBC 80/10 provides no on-board clock; so if your 80/10 system needs timed 
RQWAIT operations, you must furnish ether clock hardware in your system. Cer- 
tain programming considerations apply in interfacing clock hardware other than the 
8253 with RMX/80. These are covered in Appendix G, "iSBC 80/10 Time Base 
Considerations." 

Interrupt Handling 

Interrupt handling on the iSBC 80/20, ^0/24, or 80/30 is a service provided by 
RMX/80. Interrupt handling on the iSBC 80/ 10 or on the iSBC 80/20, 80/24, or 
80/30 when user-supplied interrupt service routines are required for especially 
response-time-critical applications, is somewhat more complex. 

RMX/80 supports all eight hardware interrupt levels on the iSBC 80/20, and all 
twelve levels (the eight supplied by the £.259 Programmable Interrupt Controller 
chip, plus the four additional levels provided on the 8085 processor) on the iSBC 
80/24 and 80/30. (The 80/30 TRAP interrupt is a special case; see discussion under 
"iSBC 80/24 and 80/30 Interrupts.") The single-level hardware interrupt on the iSBC 
80/10's is transformed via RMX/80 software into eight software interrupt levels, 
which RMX/80 treats as if they were the corresponding 80/20 hardware interrupts. 

The following section on iSBC 80/20 interrupts describes the use of RMX/80's 
interrupt handling facilities, as well as the facilities provided for writing your own in- 
terrupt service routines. Much of this material is also true for the iSBC 80/24, 80/30 
and/or 80/ 10 versions of RMX/80, so all users should read this section. (80/ 10 users 
may disregard the subsection on user-supplied routines.) The sections on iSBC 
80/24, 80/30 and iSBC 80/ 10 interrupts describe only the differences from the iSBC 
80/20 version. 

iSBC 80/20 Interrupts. A device generates an interrupt to indicate that it is ready to 
send data to the system or that it is ready to accept data from the system. In the case 
of DMA (Direct Memory Access) devices, the interrupt signals completion of the 
data transfer. 

A special set of interrupt exchanges is reserved for use with the eight hardware inter- 
rupt levels. The default names of these exchanges (and their corresponding Interrupt 
Exchange Descriptors) are RQL0EX, RQL1EX, RQL2EX,...RQL7EX; you can 
replace these defaults by means of the RQSETV operation, which associates a user- 
supplied interrupt exchange descriptor w th a particular level. Thus, a priority 48 
task communicates with level 2 interrupts (see table 2-2) via RQL2EX. Rather than 
consume the memory required to predefine all eight interrupt exchanges, RMX/80 
requires the user to define the interrupt exchanges used in his tasks. Like other 
exchanges, these may be defined either during configuration or at run time via 
RQCXCH operations. When an internist exchange is defined at run time, an 
RQELVL operation is also required to initialize the five-byte message part of the 
Interrupt Exchange Descriptor. 

Certain interrupt levels — and their associated interrupt exchanges — have been 
assigned to particular RMX/80 features. RQL1EX is normally reserved for the 
system clock. When the Terminal Handler is included in a system, it requires 
RQL6EX for input and RQL7EX for output. 

For each user-declared interrupt exchange, you must provide a task that waits at the 
exchange. This task must have a priority that corresponds to the hardware priority 
of the interrupt. For example, a task that waits at RQL2EX must have a priority in 
the range 33 through 48. The purpose of this task is to perform the required input or 
output operation after an interrupt for its exchange has been recognized. 

RMX/80 Interrupt Handling. After system initialization, when RMX/80 passes 
control to the highest priority task, all hardware interrupt levels on the iSBC 80/20 
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are disabled. The levels required by the application tasks must be enabled via the 
RQELVL operation described earlier in this chapter. 

When an interrupt is recognized, the following sequence of events occurs: 

1. The 8080 processor disables all interrupts. 

2. A context save is performed, i.e., the contents of the registers are pushed onto 
the stack. 

3. RMX/80 performs the hardware operations required to acknowledge the 
interrupt. 

4. RMX/80 then sends an interrupt message to the interrupt exchange associated 
with this interrupt level. (The interrupt message sent is the message that makes 
up the last five bytes of the Interrupt Exchange Descriptor.) If there is no 
message already waiting at this exchange, the TYPE field of the interrupt 
message is set to 01 H, INT$MSG$TYPE. If there is a message already waiting 
at this exchange — generally indicating that an interrupt at this level has oc- 
curred previously but has not yet been serviced — the TYPE field of the inter- 
rupt message already waiting at the exchange is set to 02H, 
MISSEDSINTSTYPE, and no new message is queued at the exchange. 

5. If a task is waiting at the interrupt exchange, this task is immediately made the 
running task (i.e., is put at the head of the Ready List), because its priority cor- 
responds with that interrupt level and is thus necessarily higher (lower in 
number) than the task that was interrupted. Before passing control to the user 
task, RMX/80 enables interrupts with a higher priority than the current inter- 
rupt. 

6. The user task performs any input or output operation associated with the 
interrupt and any other required processing. Input/output operations are per- 
formed through the microprocessor's I/O ports or through memory locations. 
(I/O port assignments are part of the system's hardware design.) The user task 
must not return the interrupt message. 

7. When the user task surrenders control by again waiting at the interrupt 
exchange, RMX/80 continues execution of the ready task with the highest cur- 
rent priority and resets the interrupt mask to correspond with the priority of 
that task. If the task has priority level 129 or lower (priority level nurnber 
129-255), all interrupts are enabled. 

Note that while servicing an interrupt, RMX/80 masks off interrupt levels equal to 
or lower (higher in number) than the interrupt being serviced. Thus, while a level 2 
interrupt is being serviced, hardware interrupt levels 2 through 7 are temporarily 
blocked from causing interrupt messages to be sent. However, the interrupt hard- 
ware is still able to set latches to record the occurrence of subsequent interrupts so 
that the interrupts can be received when they become unmasked. 

When you let the iSBC 80/20 version of the RMX/80 Nucleus manage the interrupt 
system for you, all you must supply is a user task or tasks to wait at the appropriate 
interrupt exchange. Typically, this task performs any input or output associated 
with the interrupt. 

As a general rule, tasks that wait at interrupt exchanges should be as brief as possible 
so that subsequent interrupts can be enabled. When an interrupt generates a great 
deal of processing, it is useful to divide the work among two or more tasks. The task 
that waits at the interrupt exchange can service the interrupt and send any necessary 
data to a task with a priority of 129-254. This second task can then process the data. 
This technique allows the enabling of subsequent interrupts as quickly as possible. 

Notice that user tasks wait at an interrupt exchange; they very seldom send a 
message to an interrupt exchange, even though RMX/80 does not prohibit such an 
operation. Sending a message to an interrupt exchange can make the receiving task 
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think an interrupt has occurred when one has not. (This can be overcome by setting 
the interrupt message's TYPE field to a type other than INT$MSG$TYPE(1) or 

MISSED$INT$TYPE(2).) Also, sending messages via an interrupt exchange might 
overload the receiving task and cause missed interrupts. (This is, however, a useful 
debugging technique.) 

Missed Interrupts. It is important to make clear that there are two different ways in 
which an interrupt arriving at the iSBC 80/20 from an external device can be 
"missed," or in other words, not translated into an interrupt message and allowed 
to wake up an interrupt task waiting at an interrupt exchange. 

In the first case, which is discussed in the previous section, the interrupt is received, 
but an interrupt message has already been sent to the exchange and not yet received 
by a task. In this case the TYPE field of the first interrupt message already queued at 
the exchange is changed to MISSEDS INT$TYPE(2), and the second interrupt 
message is not queued at the exchange. It is the responsibility of the user application 
to check for this kind of missed interrupt by testing the TYPE field of the message 
portion of the Interrupt Exchange Descriptor. Note that the RMX/80 software pro- 
vides an indication of the first missed interrupt message at a particular level, but 
does not distinguish between a single misled interrupt and a succession of missed in- 
terrupts. 

In the second case, the interrupt arrives at the appropriate hardware interrupt pin on 
the iSBC 80 (for the iSBC 80/20, this will be one of the interrupt pins on the 8259 
chip), but is held up there because the associated interrupt level is currently masked 
off by RMX/80. In this case, the interrupt signal is not translated into an interrupt 
message until RMX/80 unmasks that interrupt level. If a second interrupt occurs 
before the level is unmasked (acknowledged), no record of the first will remain. 

Note that the second case will always hold true when a second interrupt signal ar- 
rives while the task designated to service i hat interrupt level is running in response to 
an earlier occurrence of the interrupt. (The fact that the interrupt service task is run- 
ning means that all interrupts of that level or lower are masked off.) The second case 
will also hold true if a task servicing a higher-priority interrupt is running. The first 
case may be true only if the task servicing the interrupt level in question is waiting at 
an exchange other than the interrupt exchange, and a lower-priority task is currently 
running. In this situation the interrupt evel will not be masked off and interrupt 
signals arriving at that level will be translated by RMX/80 into an interrupt message, 
which will be queued at the interrupt exchange until the interrupt task is made run- 
ning again. 



In defining and coding your application tasks for servicing interrupts, it is important 
for you to be aware of the possibilities discussed in the preceding paragraphs. There 
are ways in which you can minimize the chances of missing interrupts, while keeping 
your application efficient. For instance, if a task servicing a high-priority interrupt 
(e.g., for terminal input) must also wait at another (non-interrupt) exchange, you 
could split this task into two separate tasks— one to wait at the interrupt exchange 
and store incoming data in a buffer, the other to wait at the other exchange and pro- 
cess the buffer as it is able to. 

User-Supplied Interrupt Service Routines. The iSBC 80/20, 80/24, and 80/30 
versions of RMX/80 provide three operations to support user-supplied interrupt 
routines: RQSETV, RQISND, and RQENDI. 

To make use of these facilities, you should set up your interrupt service routine with 
a call to RQSETV, which substitutes the address of a user-supplied PL/M pro- 
cedure or assembly-language subroutine in place of RMX/80's normal 
interrupt-handling software. When an interrupt for which an RQSETV opera- 
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tion has been given is recognized, control passes immediately to the specified 
PL/M procedure or assembly-language subroutine. (In effect, RQSETV 
substitutes a CALL instruction for the normal RMX/80 software.) This has 
several programming implications: 

• Because the normal RMX/80 software is bypassed, the user-supplied routine 
receives control without benefit of any software services. The interrupt mask re- 
mains unchanged, and no context save for the executing task is performed. This 
requires the user-supplied task to save and restore any registers modified by the 
interrupt service routine. (The PL/M compiler will generate code to save and 
restore the registers if your interrupt routine is declared an INTERRUPT pro- 
cedure. If you use an INTERRUPT procedure, note that you must specify the 
primary control SNOINTVECTOR at the beginning of the module.) 

• Under no circumstances should an EI (Enable Interrupts) instruction be 
executed within the user-supplied routine. This can cause a loss of system in- 
tegrity. However, the user-supplied routine must enable interrupts when it 
returns control to the task preempted by this interrupt. These seemingly conflic- 
ting requirements can be met because of a feature of the EI instruction. The ef- 
fect of the Enable Interrupts instruction is delayed until the next sequential in- 
struction has been executed. Therefore, the instruction sequence EI, RET 
(return) meets the requirement of not executing an Enable Interrupts within the 
user-supplied routine, but also enables interrupts before returning to the 
preempted task. (Note that the code generated by the PL/M compiler for an IN- 
TERRUPT procedure satisfies this requirement.) 

• The user-supplied routine is either a PL/M procedure or an assembly-language 
subroutine operating completely outside the normal RMX/80 task framework. 
Therefore, the routine has no particular priority or environment of its own. The 
routine must draw its resources from whatever task was running when the inter- 
rupt occurred. Any registers and stack space used by the routine are taken from 
that task. Since the occurrence of an interrupt cannot be predicted, all tasks in 
the system must reserve enough stack space for their own needs, 48 bytes for an 
RMX/80 context save, and sufficient stack space for the needs of the user- 
supplied interrupt service routine(s). User-supplied routines that use excessive 
amounts of stack space may cause stack overflows in the Terminal Handler 
and/or Free Space Manager. Alternatively, the user-supplied routine can create 
its own stack. This is done by reserving the required space in RAM. When the 
user-supplied routine begins execution, it saves the current Stack Pointer and 
replaces it with the address of its own stack. The routine must restore the Stack 
Pointer before returning control to the preempted task or calling RQISND, 
whichever is done first. 

• When the user-supplied routine begins execution, the top of the stack contains 
the return address needed to resume execution of the task running when the in- 
terrupt was recognized. The user-supplied interrupt needs this address to return 
to the interrupted task. 

Because the user-supplied routine operates completely outside the RMX/80 task 
framework, the normal RMX/80 operations cannot be used. RMX/80 provides the 
RQENDI and RQISND operations to overcome this limitation. These are the only 
RMX/80 operations that should be called from within a user-supplied interrupt ser- 
vice routine. 

RQENDI and RQISND both signal the RMX/80 software that the interrupt has 
been serviced. RMX/80 then acknowledges the interrupt. RQISND has the extra 
function of sending a message to the specified interrupt exchange. This has the effect 
of starting execution of any task waiting at that interrupt exchange, thereby re- 
entering the RMX/80 software environment. System conventions require that the 
task invoked by RQISND run at a priority level associated with the interrupt ex- 
change. Remember that all lower-priority tasks are still blocked from executing by 
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the RMX/80 software. Therefore, interrupts with a priority equal to or lower than 
the task invoked by the RQISND are disabled. RMX/80 alters this condition only 
when the task invoked by the RQISND surrenders control of the processor. 

As mentioned previously, RQENDI acknowledges the hardware interrupts on the 
iSBC 80. It is particularly useful when the user-supplied interrupt routine must 
handle a burst of interrupts. Typically, such a user-supplied routine handles a whole 
string of data before calling RQISND. 

The flowchart of figure 2-2 illustrates the interaction between a user-supplied inter- 
rupt service routine and a task that waits at an interrupt exchange. The user-supplied 
routine fills a buffer with input data. When the buffer is full, the user-supplied 
routine wakes up a task by sending an interrupt message to an interrupt exchange via 
an RQISND operation. 

Because the interrupt task has a priority that corresponds to the hardware interrupt 
that invoked the RQSETV interrupt routine, further interrupts at this level are 
blocked until the interrupt task again waits at the interrupt exchange. Therefore, the 
buffer can be processed and re-initialized before another interrupt can alter the buf- 
fer. In many cases, processing the buffer may consist only of sending the data to a 
lower priority task. Note that all application processing code in the RQSETV 
routine must precede the RQENDI or RQISND operation. 

The following PL/M listing illustrates a typical user-supplied interrupt service 
routine for the iSBC 80/20, following the example flowcharted in figure 2-2. Note 
that since a PL/M INTERRUPT procedure is used, the primary control SNOINT- 
VECTOR must be specified at the beginnir g of the module, to prevent the compiler 
from attempting to write a restart vector over ROM used by RMX/80 code. 
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Figure 2-2. Buffered Input via User-Supplied Interrupt Service Routine 
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$NOINTVECTOR 
SERVICE: 



/* EXTERNALS*/ 

DECLARE DATA$BUFFER(1) BYTE EXTERNAL; 
DECLARE DATASPNTR ADDRESS EXTERNAL; 
DECLARE DATASCOUNT ADDRESS EXTERNAL; 

RQISND: 

PROCEDURE(IED$ADDRESS) EXTERNAL; 

DECLARE IEDSADDRESS ADDRESS; 
END RQISND; 

RQENDI: 

PROCEDURE EXTERNAL; 
END RQENDI; 

/"PUBLICS*/ 

DECLARE RQL7EX(15) BYTE PUBLIC; 

INTSSVC: 

PROCEDURE INTERRUPT 7; 

DECLARE DATASPORT LITERALLY 'OECH'; 

DATA$BUFFER(DATA$PNTR) = INPUT(DATASPORT); 

DATASPNTR = DATASPNTR + 1 ; 

IF DATASPNTR >= DAT ASCOUNT THEN 

CALL RQISND(.RQL7EX); 
ELSE 

CALL RQENDI; 

END INTSSVC; 

END SERVICE; 

BLOCKSREAD: 
DO; 

/* PUBLICS */ 

DECLARE FOREVER LITERALLY 'WHILE V; 
DECLARE DATA$BUFFER(256) BYTE PUBLIC; 
DECLARE DATASPNTR ADDRESS PUBLIC; 
DECLARE DATASCOUNT ADDRESS PUBLIC; 
DECLARE REQ$EXC EXCHANGE$DESCRIPTOR PUBLIC; 

/* EXTERNALS*/ 

DECLARE RQL7EX(15) BYTE EXTERNAL; 

INTSSVC: 

PROCEDURE EXTERNAL; 
END INTSSVC; 

RQSETV: 

PROCEDURE(SERVICE$ADDRESS,INT$LEVEL) EXTERNAL; 
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DECLARE SERVICESADDRESS ADDRESS, 
INTSLEVEL BYTE; 
END RQSETV; 
RQELVL: 

PROCEDURE(INT$LEVEL) EXTERNAL; 

DECLARE INTSLEVEL BYTE; 
END RQELVL; 



RQDLVL: 

PROCEDURE(INTSLEVEL) EXTERNAL; 

DECLARE INTSLEVEL BYTE; 
END RQDLVL; 



RQSEND: 

PROCEDURE(EXCHANGE$ADDRESS,MESSAGE$ADDRESS) EXTERNAL; 

DECLARE(EXCHANGE$ADDRESS, MESSAGESADDRESS) ADDRESS; 
END RQSEND; 

RQWAIT: 

PROCEDURE(EXCHANGE$ADDRESS,VIESSAGE$ADDRESS) 

ADDRESS EXTERNAL; 

DECLARE(EXCHANGE$ADDRESS,MESSAGE$ADDRESS) ADDRESS; 
END RQWAIT; 

USARTSREADER: /'MUST BE A TASK WITH PRIORITY 113-128* / 
PROCEDURE PUBLIC; 

DECLARE MSGSPNTR ADDRESS; 

DECLARE MSG BASED MSGSPNTR STRUCTURE( 

LINK ADDRESS, 
LENGTH ADDRESS, 
TYPE BYTE, 

HOMESEXCHANGE ADDRESS, 
RESPONSESEXCHANGE ADDRESS, 
ADDR ADDRESS); 

DECLARE INTRSMSG ADDRESS; 



CALL RQSETV(.INT$SVC,7); 



DO FOREVER; 

MSGSPNTR = RQWAIT(.REQSEXC,0); 

DATASPNTR = 0; 

DATA$COUNT = 256; 

CALL RQELVL(7); 

INTRSMSG = RQWAIT(.RQL7E>,0); 

CALL RQDLVL(7); 

MSG. ADDR = .DATASBUFFER; 

CALL RQSEND(MSG.RESPONJ;E$EXCHANGE, MSGSPNTR); 



END; /*OFDO FOREVER*/ 
END USARTSREADER; 



END BLOCKSREAD; 

iSBC 80/24 and 80/30 Interrupts. The iSBC 80/24 and 80/30 versions of 
RMX/80 process interrupts in essentially the same way as the iSBC 80/20 version. 
The differences lie in RMX/80's support of the additional interrupt levels available 
on the 8085 processor chip on the iSBC 80/24 and 80/30. These levels (TRAP, RST 
7.5, RST 6.5 and RST 5.5) are recognized by RMX/80 as byte values 8, 9, 10, and 1 1, 
respectively; the PL/M INCLUDE file INTRPT.ELT assigns them the symbolic 
values "TRAP," "ASLEV," "B$LEV," and "CSLEV," respectively. The priorities of 



these interrupts are higher than the levels 0-7 provided on the 8259 Programmable 
Interrupt Controller chip. (For a list of the software priorities corresponding to each 
of the iSBC 80/24 and 80/30 interrupts, refer to table 2-2.) 



RMX/80 Interrupt Handling. The following differences (from the 80/20 version) 
apply to the iSBC 80/24 and 80/30 versions: 

• The 80/24 and 80/30 versions of RMX/80 defines eleven interrupt exchanges: 
RQLAEX, RQLBEX, RQLCEX, and RQL0EX through RQL7EX. No 
interrupt exchange is associated with the TRAP interrupt; the special case of this 
interrupt is discussed later in this section. 

• The RQELVL and RQDLVL operations recognize the additional interrupt 
levels available on the iSBC 80/24 and 80/30. (However, since the TRAP 
interrupt cannot be masked off, use of the TRAP level parameter (8) with 
RQELVL or RQDLVL has no effect.) 

User-Supplied Interrupt Service Routines. The facilities provided by the iSBC 80/24 
and 80/30 for handling user-supplied interrupt service routines are identical to those 
of the iSBC 80/20, with two exceptions: 

• The RQISND operation recognizes the address of any of the eleven Interrupt 
Exchange Descriptors defined for the iSBC 80/24 and 80/30. 

• The RQSETV operation recognizes all twelve interrupt levels available on the 
iSBC 80/24 and 80/30. (However, use of the TRAP interrupt is subject to special 
cautions, which are discussed in the following paragraphs.) 



Notes on 8085 Hardware Interrupts. Note that: 

• The TRAP interrupt (TRAP pin on the 8085) is edge/level-triggered. The 
interrupting signal must go high and stay high to trigger an interrupt. 

• The ASLEV interrupt (RST 7.5 pin on the 8085) is edge-triggered. A pulse on 
this line will set an internal flip-flop. The 8085 automatically resets this flip-flop 
when it passes control to the level 7.5 interrupt service routine. The flip-flop will 
be set (interrupt pending) even when the ASLEV interrupt is masked out {using 
a call to RQDLVL), and the interrupt will be acknowledged if and when ASLEV 
is unmasked and re-enabled. (This pending interrupt may optionally be 
eliminated by a user task using an assembly language SIM instruction.) 

• The BSLEV and CSLEV interrupts (RST 6.5 and RST 5.5 pins on the 8085) are 
level-triggered. A high level occurring on either of these pins while the cor- 
responding interrupt level is unmasked and enabled will cause an interrupt to be 
acknowledged. 



Because of the triggering sensitivity of the BSLEV and CSLEV interrupts, it is the 
responsibility of the user tasks waiting on the RQLBEX and RQLCEX interrupt ex- 
changes to remove the interrupting signal before a lower-priority task is activated. If 
this is not done, the same interrupt could be processed repeatedly. The ASLEV inter- 
rupt is automatically reset when control is passed to the corresponding interrupt 
routine or task. 



The 8085 on-chip interrupt TRAP is not maskable by any means. Because it is not 
restricted by any mask or hardware Disable Interrupts (DI) command, it can inter- 
rupt any routine, even in "protected regions" of code which should never be inter- 
rupted. Therefore its use is strongly discouraged for all but emergency situations 
(such as a power fail/restart capability). No interrupt exchange is associated with the 
TRAP level, since it should never cause a call to RQISND (see next paragraph). 
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An interrupt on the TRAP line is initially vectored by RMX/80 to a HALT com- 
mand which will stop processing without e. context save. A user who wants to use the 
TRAP interrupt must first make a call to RQSETV for the TRAP level, which will 
place the address of a special user-supplied TRAP interrupt service routine in the in- 
terrupt vector. Such a TRAP interrupt service routine should not make use of any 
RMX/80 operations; not even RQISND should be called. (RQISND is "protected" 
from all other interrupts, but cannot be protected from the TRAP interrupt.) As 
with other user-supplied interrupt service routines, all context saves are the respon- 
sibility of the service routine itself. 



iSBC 80/10 Interrupts. The iSBC 80/ 10A and 80/ 10B have a single hardware 
interrupt level (level 7), which is transformed via software into an eight-level priority 
system. RMX/80 then treats these eight levels, in terms of messages and exchanges, 
as if they were the eight hardware interrup : levels on the iSBC 80/20. The same set of 
interrupt exchanges (RQL0EX, RQL7 EX) is defined, and an interrupt exchange 
is created and initialized in the same way (during RMX/80's initialization using the 
configuration module, or at run time via RQCXCH and RQELVL). The sequence of 
events described under "iSBC 80/20 Interrupts" holds true with two exceptions: the 
enabling and disabling of interrupts differs, and RMX/80 must consult user-supplied 
polling routines before processing the interrupt. 

On the iSBC 80/ 10's, the rules for enabling and disabling interrupt levels are different. 
Because interrupt levels through 7 on the 80/10's are actually software pseudo- 
interrupt levels, all corresponding to the same hardware interrupt, the only two 
possible conditions are "all interrupts enabled" and "all interrupts disabled." If the 
running task on an 80/ 10 has a software priority level in the range through 128, 
(this will generally be an interrupt-driver task), RMX/80 automatically disables 
interrupts. If the running task has a softwere priority in the range 129 through 255, 
RMX/80 enables all interrupts. The RQELVL and RQDLVL operations have no 
interrupt enabling or disabling effect on the iSBC 80/10's. 

When an iSBC 80/ 10 accepts an interrupt, it disables all subsequent interrupts until 
the current interrupt has been serviced. Servicing an interrupt on the iSBC 80/10's 
typically requires an input or output operation; the hardware interrupt remains 
outstanding and continues to interrupt the system until an I/O operation occurs. 

Because all interrupts arrive at the same hardware level, RMX/80 cannot determine 
which device generated the interrupt, and consequently what software pseudo- inter- 
rupt level is concerned. Therefore, you must provide a processing routine (polling 
routine) for each class of devices that may generate an interrupt. The RQSETP 
operation is provided for this purpose; further details on this operation are given 
earlier in this chapter. Each of your polling routines must perform at least the 
following operations: 

• Test the hardware associated with the procedure to determine if it produced the 
interrupt. 

• If no interrupt originated from the hardware managed by the procedure, return 
the byte value FALSE = OOFf (in the accumulator) to the calling program. 

• If an interrupt is present: 

a. Process it by acknowledging the hardware as required; 

b. Send an interrupt message to the associated interrupt exchange 
(IED=RQL0EX, ...,RQL7EX) by calling RQISND, or process the inter- 
rupt directly; and 

c. Return the byte value TRUE=0FFH (in the accumulator) to the calling 
program. 

These routines must not enable interrupts. 
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Note that these routines are not interrupt service routines, insofar as they do not 
need to save context, because RMX/80 does this before calling them. The routines 
are invoked in order of priority by RMX/80 until one of them returns a TRUE 
value, or until all eight have been called . In the event that all interrupt procedures 
are called and none of them indicate that the interrupt was acknowledged, the iSBC 
80/10 will enter the halt state with interrupts disabled. This is a catastrophic error 
condition. 

Further note that if your application requires fewer than eight interrupt levels, you 
need not provide interrupt polling routines for the unused levels; the default inter- 
rupt routine for all eight levels is a routine that always returns FALSE. 

Because the 80/10's lack priority interrupt logic, RMX/80 disables all interrupts 
when it activates a task with priority less than or equal to 128. This makes it particu- 
larly important that your application code not disable and enable interrupts. 

PL/M programmers must declare the polling routine as a byte-type procedure and 
return a TRUE (OFFH) or FALSE (00H) indication to RMX/80. Assembly-language 
programmers must load the accumulator with OFFH if the routine accepts respon- 
sibility for the interrupt or 00H if not, then execute a RET (return) instruction. 
(Since the subroutine is invoked by a CALL instruction, the return address is on the 
top of the stack. If the subroutine uses the stack, it must also clear its own data from 
the stack before returning so that the return functions properly.) 

The RQISND operation functions normally in the iSBC 80/ 10A or 80/ 10B 
environments. It acknowledges the interrupt and sends a message to an interrupt 
exchange. However, you must be certain that the task invoked by the RQISND 
operation acknowledges the interrupt if the RQSETP routine does not do so. 

iSBC 80/ 10A or 80/ 10B users can totally replace the RMX/80 interrupt software by 
directing interrupts to user-supplied routines via an RQSETV operation. If the user 
directs all level 7 interrupts to user code, RMX/80 does not even know when an 
interrupt occurs. Of course, the user must assume total responsibility for all 
interrupts. In this situation the RQSETP operation has no meaning, since RMX/80 
does not take part in interrupt processing. RQISND is the only operation with any 
meaning in such user-supplied interrupt service routines on the iSBC 80/ 10's. 

The following PL/M listing illustrates a typical user-supplied interrupt service 
routine for the iSBC 80/ I0A or 80/ 10B. This procedure performs the same function 
on an 80/ 10 system as the example under "iSBC 80/20 Interrupts" does on an 80/20. 



SERVICE: 
DO; 

/* EXTERNALS */ 

DECLARE DATA$BUFFER(1) BYTE EXTERNAL; 
DECLARE DATA$PNTR ADDRESS EXTERNAL; 
DECLARE DATA$COUNT ADDRESS EXTERNAL; 

RQISND: 

PROCEDURE(IED$ADDRESS) EXTERNAL; 

DECLARE IEDSADDRESS ADDRESS; 
END RQISND; 

RQENDI: 

PROCEDURE EXTERNAL; 
END RQENDI; 



/* PUBLICS*/ 



DECLARE RQL7EX(15) BYTE PUBLIC; 

INT$SVC: 

PROCEDURE BYTE; 

DECLARE DATASPORT LITERALLY 'OECH', 
STATUSSPORT LITERALLY 'OEDH', 
RECEIVE$READY LITERALLY '002H'; 

IF INPUT(STATUS$PORT) AN D (RECEIVESREADY > 0) THEN DO; 
DATA$BUFFER(DATA$PNTR) = INPUT(DATASPORT); 
DATASPNTR = DATA$PNTR + 1 ; 

IF DATA$PNTR <- DAT ASCOUNT THEN CALL RQISND(.RQL7EX); 

RETURN(OFFH); 

END; 

ELSE RETURN(OOH); 
ENDINTJSVC; 

END SERVICE; 



BLOCKSREAD: 
DO; 

/* PUBLICS*/ 

DECLARE FOREVER LITERALLY WMLE V; 
DECLARE DATA$BUFFER(256) BYTE PUBLIC; 
DECLARE DATA$PNTR ADDRESS PUBLIC; 
DECLARE DATA$COUNT ADDRESS PUBLIC; 
DECLARE REQ$EXC EXCHANGE$DESCRIPTOR PUBLIC; 

/•EXTERNALS*/ 

DECLARE RQL7EX(15) BYTE EXTERNAL; 

INT$SVC: 

PROCEDURE EXTERNAL; 
ENDINTSSVC; 

RQSETP: 

PROCEDURE(SERVICE$ADDRESS,INT$LEVEL) EXTERNAL; 

DECLARE SERVICESADDRESS ADDRESS, INTSLEVEL BYTE; 
END RQSETP; 

RQSEND: 

PROCEDURE(EXCHANGE$ADDRE3S,MESSAGE$ADDRESS) EXTERNAL; 

DECLARE(EXCHANGE$ADDRE3S,MESSAGE$ADDRESS) ADDRESS; 
END RQSEND; 

RQWAIT: 

PROCEDURE(EXCHANGE$ADDRESS,TIME$LIMIT) EXTERNAL; 

DECLARE(EXCHANGE$ADDRESS,TIME$LIMIT) ADDRESS; 
END RQWAIT; 



USARTSREADER: /*MUST BE A TASK WITH PRIORITY 113-128*/ 
PROCEDURE PUBLIC: 

DECLARE ENABLESUSART LITERALLY '037H', 
DISABLESUSART LITERALLY '033H', 
USARTSCONTROL LITERALLY 'OEDH'; 
DECLARE MSGSPNTR ADDRESS; 
DECLARE MSG BASED MSGSPNTR STRUCTURE( 

LINK ADDRESS, 
LENGTH ADDRESS, 
TYPE BYTE, 

HOMESEXCHANGE ADDRESS, 
RESPONSESEXCHANGE ADDRESS, 
ADDR ADDRESS); 

DECLARE INTRSMSG ADDRESS; 

CALL RQSETP(.INT$SVC,7); 

DO FOREVER; 

MSGSPNTR = RQWAIT(.REQ$EXC,0); 
DATASPNTR = 0; 
DATA$COUNT = 256; 

OUTPUT(USARTSCONTROL) = ENABLESUSART; 
INTRSMSG = RQWAIT(.RQL7EX,0); 
OUTPUT(USARTSCONTROL) = DISABLESUSART; 
MSG. ADDR = .DATASBUFFER; 

CALL RQSEND(MSG.RESPONSE$EXCHANGE, MSGSPNTR); 
END; /*OF DO FOREVER */ 
END USARTSREADER; 
ENDBLOCKSREAD; 



Details of System Operation 

The information given below is intended primarily for debugging purposes and for 
those who want additional details of system operation. You should not need this in- 
formation to write tasks for the RMX/80 environment. You should, however, be 
familiar with this information if you plan to code configuration modules in PL/M. 

Figure 2-8 at the end of this chapter is a summary, in diagram form, of the informa- 
tion provided in this section. It is designed to serve as a convenient reference for 
understanding the system and for debugging. 



System Initialization 

RMX/80 is designed to initialize a system without the need for any external program 
loading devices. The system initializes itself by building control structures in RAM 
from structures you supply during configuration. Initialization without external 
storage devices requires that these structures be located in ROM. In addition, while 
configuring you must specify the RAM required for the control structured to be 
generated. 

Three user-supplied structures are required for system initialization. The first of 
these is the Create Table (RQCRTB). This table is simply a set of pointers to the 
other two structures, the Initial Task Table and the Initial Exchange Table. The In- 



itial Task Table (ITT) is a list of Static Task Descriptors; the Initial Exchange Table 
(IET) is a list of addresses where the system is to build Exchange Descriptors. Figure 
2-3 shows the relationship between the Create Table, the Initial Task Table, and the 
Initial Exchange Table. 

Whenever the system is started, the RMX/80 Nucleus uses these structures in ROM 
to build Task Descriptors and Exchange Descriptors in RAM. RMX/80 performs an 
RQCTSK operation for each Static Task Descriptor in the Initial Task Table. (There 
must always be at least one Static Task Descriptor in the table.) The Nucleus builds 
an Exchange Descriptor for each exchange address specified in the Initial Exchange 
Table. Each Exchange Descriptor is built via an RQCXCH operation. 

Only the tasks and exchanges specified in the configuration module are created at in- 
itialization. However, other tasks and exchanges may be created at run time by ap- 
plication tasks or RMX/80 extension tasks via the RQCTSK and RQCXCH opera- 
tions. 

After the RMX/80 Nucleus builds the Task Descriptors and Exchange Descriptors 
specified in the configuration module, it determines which task has the highest 
priority and passes control to that task. 



Static Task Descriptor 

A diagram of the Static Task Descriptor is given in figure 2-4. The fields of this 
structure are described below. 

NAME contains a string of six ASCII characters giving the name of the task. 

INITIAL PROGRAM COUNTER contains the address of the first instruction to be 
executed by the task. 

STACK ADDRESS contains the (lowest numeric) address of the RAM to be used as 
the task's stack. 

STACK LENGTH contains the number of bytes of RAM allocated to the task's 
stack. 

PRIORITY contains the task's software priority level. 

INITIAL EXCHANGE contains the address of the task's initial default exchange, 
or zero if there is no default exchange. 

TASK POINTER contains the starting address of the 20 bytes of RAM to be used as 
the task's Task Descriptor. 
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Figure 2-3. System Initialization Structures 
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Structure. Some of the information in the Task Descriptor is simply transferred 
directly from the Static Task Descriptor. The Task Descriptor is built at the RAM 
address specified by the TASK POINTER field in the Static Task Descriptor, as 
shown in figure 2-5. Arrows show values moved from the Static Task Descriptor to 
the Task Descriptor when the system is started. 

The STACK POINTER in the Task Descriptor is set equal to STACK ADDRESS + 
STACK LENGTH from the Static Task Descriptor. The MARKER field is the 
lowest numeric address available for the task's stack. The Debugger uses the 
MARKER field to detect stack overflow. The RMX/80 Nucleus does not check for 
stack overflow because of the overhead this would impose on the system. 

After the task's stack is created, RMX/80 pushes the INITIAL PROGRAM 
COUNTER from the Static Task Descriptor onto the stack. Whenever a task is not 
running, its program counter is stored on the stack. RMX/80 fills the remainder of 
the stack with the value 0C7H. This is an additional debugging aid, since it makes it 
possible for you to see how much of the stack has been used. 

Notice that the EXCHANGE ADDRESS field is initially set to the corresponding 
value from the Static Task Descriptor. This field provides a default exchange ad- 
dress for RQWAIT and RQACPT operations that specify an exchange address value 
of zero. However, this address is altered when the task is running. EXCHANGE 
ADDRESS always points to the exchange where the task is currently waiting or 
where it last waited or accepted a message; the value in this field is reset each time 
the task names an exchange in an RQWAIT or RQACPT operation. 

DELAY LINK FORWARD and DELAY LINK BACK are used for entering the 
Task Descriptor on the system Delay List when necessary, these point to the next 
and previous tasks on the Delay List. 
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Figure 2-5 . Static Task Descriptor - Task Descriptor Relationships 
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THREAD is a general-purpose field used to link the Task Descriptor onto the Ready 
List or Suspend List. This field is also used to link the Task Descriptor onto an ex- 
change's list of waiting tasks. 



DELAY/MESSAGE is another multi-purpose field. When the task is in a timed 
wait, this field of the first Task Descriptor on the Delay List indicates the remaining 
delay time, expressed in system time units. The first task on the Delay List has the 
least remaining delay. In subsequent Task Descriptors on the Delay List, the field in- 
dicates the additional delay required for that task after the delay for the preceding 
task has expired. When the task receives s message, the address of the message is 
temporarily stored in this field. When the task becomes the running task, this ad- 
dress is placed in the H and L registers. 



STATUS is a one-byte field. Individual bits of this field indicate task status: 

• Bit 0, DELAYEDSTASK: Bit is set to 1 if the task is on the Delay List. 

• Bit 1 , SUSPENDEDSTASK: Bit 1 is set to 1 if the task is on the Suspend List or 
if it is to be placed there when it next becomes ready. 

• Bit 2, PREEMPTEDSTASK: Bit 2 is set to 1 when the task is preempted by a 
hardware interrupt. 

• Bits 6 and 7, DEBUGSBITS: Bits 6 and 7 are reserved for use by the RMX/80 
Debugger. 

NAME POINTER contains the address of the Static Task Descriptor used to create 
the task (and thus the address of the task's name). 

TASK LINK links the Task Descriptor to a list of all the tasks in the system. 



Accessing the Task Descriptor. A task must not alter its own or any other task's 
Task Descriptor. However, it may be useful for a task to read its own EXCHANGE 
ADDRESS, NAME POINTER, PRIORITY, and MARKER fields. If a task does 
not know the address of its own Task Descriptor, the Task Descriptor can be ac- 
cessed through the public address variable RQACTV. RQACTV always points to 
the Task Descriptor of the running task. 
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MESSAGE HEAD is a pointer to the first message waiting at the exchange. This 
field is set to zero if no message is waiting at the exchange. 

MESSAGE TAIL is a pointer to the last message waiting at the exchange. If no 
message is waiting, this field is set to the address of the exchange. 

TASK HEAD is a pointer to the first task waiting at the exchange. If no task is 
waiting, this field is set to zero. 

TASK TAIL is a pointer to the last task waiting at the exchange. If no task is 
waiting, this field is set to the address of the exchange. 

EXCHANGE LINK contains the address of the next Exchange Descriptor in the list 
of all the Exchange Descriptors in the system. 

Note that because of the way tasks and messages are queued at exchanges, a task can 
wait at only one exchange at a time. 



Use in System. The following example illustrates the use of an exchange. For the 
sake of simplicity, assume that the Exchange Descriptor is located at address 4500; 
the messages sent to the exchange are at locations 4100, 4200, and 4300. When first 
created, the Exchange Descriptor is set to the following values (the use of the EX- 
CHANGE LINK field is not shown): 



4500 


1500 



Assume that a task sends the message at location 4100 to the exchange. The 
MESSAGE HEAD and MESSAGE TAIL fields change as shown: 

4100 
4100 



4500 
xx 



Since there is only one message at the exchange, the MESSAGE HEAD and 
MESSAGE TAIL fields are the same. TASK HEAD and TASK TAIL remain un- 
changed. 

Now assume that a task sends the message at location 4200 to the exchange. The Ex- 
change Descriptor is changed as shown: 

4100 
4200 



4500 



When the third message is sent, the Exchange Descriptor is altered as follows: 

4100 
4300 








xx 



Notice that address 4200 no longer appears in the Exchange Descriptor. This raises 
the question of how the system knows where the second message is located. This in- 
formation is stored in the LINK field of the message heading. The LINK field (the 
first two bytes) of the first message contains the address of the second message; the 
LINK field of the second message contain:; the address of the third message. 

Now consider the effect of a task issuing an RQWAIT at this exchange. There is no 
need to queue the task at the exchange, since there is a message available. (Tasks are 
queued at exchanges using the same techniques as messages. When multiple tasks 
wait at the exchange, they are linked together by entries in the THREAD field of the 
Task Descriptor. In this case, the THREAD field serves the same purpose as the 
LINK field of the message heading.) 

The waiting task is given access to the first message waiting at the exchange by mov- 
ing the address in MESSAGE HEAD to the DELAY/MESSAGE field in the Task 
Descriptor. RMX/80 updates the MESSAGE HEAD by moving the address in the 
LINK field of the first message into MESSAGE HEAD. The Exchange Descriptor is 
updated so that the message at location 4200 is the first message waiting at the ex- 
change. 

Interrupt Exchange Descriptor 



Structure. As shown in figure 2-7, an Inter upt Exchange Descriptor is sixteen bytes 
long and consists of two parts. The first ten bytes correspond to the ten bytes of a 
regular Exchange Descriptor, and the fields are used in exactly the same way. The 
last six bytes are a short message consisting only of the three required message fields 
(LINK, LENGTH, and TYPE) and the LEVEL of the interrupt. 

The two parts of the Interrupt Exchange Descriptor are logically separate; they are 
contiguous in memory only for convenience to the RMX/80 software. An interrupt 
message need never be longer than six bytes, since the only information it needs to 
convey is that an interrupt has occurred at the corresponding level, and whether or 
not there has been a missed interrupt. 

Use in System. As discussed under "iSBC 80/20 Interrupts," one Interrupt Ex- 
change Descriptor must be defined for each interrupt level that is used in the system. 
The Interrupt Exchange Descriptor is initialized either at system initialization time 
tsing information in the configuration module, or at run time via an RQCXCH 
operation (for the Exchange Descriptor portion) and an RQELVL operation (for the 
message portion). When an interrupt occurs at a given level, RMX/80 sends the 
lessage portion of the appropriate Interrupt Exchange Descriptor to that interrupt 
exchange — i.e., it takes the address of the message portion and adds it to the list of 
messages linked to the Interrupt Exchange Descriptor. The TYPE field of the 
message is set to INT$MSG$TYPE(1). Before it sends the interrupt message to the 
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Figure 2-7. Interrupt Exchange Descriptor 
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exchange, RMX/80 checks to see if there is already an interrupt message queued at 
the exchange. If so, the queued message's TYPE is set to MISSED$INT$TYPE(2) 
and the second interrupt message is simply dropped. 

The LEVEL field is used by the Nucleus to send an end-of-interrupt signal to the 
8259A Programmable Interrupt Controller. This enhances performance by enabling 
the Nucleus to re -enable interrupts before an interrupt has been completely serviced 
by an interrupt service routine. The LEVEL field must be set by a call to RQELVL. 

The following example illustrates the use of an interrupt exchange. For simplicity, 
assume that the Interrupt Exchange Descriptor is for level three and is located at 
address 5000. 

When first created, the Interrupt Exchange Descriptor is set to the following values 
(the use of the EXCHANGE LINK field is not shown). Note that the LINK field of 
the interrupt message is set to its own address. This indicates that it is not queued at 
the exchange. 



" I ' 1 3 | 

Assume that an interrupt causes an interrupt message to be sent to this exchange. 
The MESSAGE HEAD and MESSAGE TAIL pointers are set to the address of the 
interrupt message, and the message's LINK field is set to zero. The Interrupt Ex- 
change Descriptor will therefore appear as follows: 




" r 



If another interrupt message is posted at the exchange before a task has become 
available to receive the first message, the IED will be changed as shown below. (The 
type of the interrupt message will be changed to MISSED$INT$TYPE(2), but the 
new message will not be queued at the exchange.) 




Now suppose that a task arrives to wait at the exchange. The task will receive the 
first message; i.e., the address in the MESSAGE HEAD field of the Interrupt Ex- 
change Descriptor will be moved to the DELAY/MESSAGE field in the Task 
Descriptor. The address in the LINK field of the message— in this case zero, since 
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only the first message is queued at the exchange — is moved into MESSAGE HEAD. 
MESSAGE HEAD is now zero, indicating that no messages are left in the queue, 
and MESSAGE TAIL is set to point to thz address of the exchange. 




The receiving task (or some other task) cai check the TYPE field of the message and 
determine that one or more interrupt messages were missed. 
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Figure 2-8. RMX/80 System Control Structures 
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CHAPTER 3 

IMPLEMENTING AN RMX/80 SYSTEM 



This chapter provides instructions for building your application system around 
RMX/80 software. 

Although developing a real-time, multitasking system is a creative process, a dis- 
cussion of the steps involved can significantly reduce the amount of time expended 
during system development. Such a discussion is provided within this chapter. 

Additionally, this chapter enumerates the requirements of the Nucleus that must 
be considered while the system is being developed. It also supplies suggestions for 
making the most effective use of the features of RMX/80. 

In building your RMX/80 application, you must perform the following basic steps: 

1 . Design the system, defining hardware and software components. 

2. Code user tasks and translate them via in Intel language translator. 

3. Generate the software configuration — i.e., prepare the configuration module, 
then link and locate object modules. 

4. Test and debug the system. 

5 . Burn the code into PROM . 



Designing Your System 

System design consists of determining the a nswers to these questions: 

• What operations must the system perform? 

• What hardware components (iSBC products, peripherals) are needed? 

• What software components (RMX/80 Nucleus code and extension tasks, user 
tasks) are needed? 

• In what physical memory spaces (ROM, RAM, on-board memory, off-board 
memory) will the software component; and data reside? 

The answer to the first question, of course, largely determines the answers to the 
other three. The other three questions, however, cannot be answered sequentially; 
hardware, software, and the location of software and data in hardware are closely 
interrelated. As the design and implementation proceed, changes made in the 
planned hardware configuration may affect the software configuration, and vice 
versa. Designing a system should therefore be treated as an iterative process. 

During the system development process, the hardware and software configuration 
usually will, out of necessity, go through a series of changes. It will generally be 
desirable to test some hardware and software components before others are ready. 
The Intellec Microcomputer Development System, with its resident diskette 
operating system (ISIS-II) and the ICE-80 or ICE-85 In-Circuit Emulator option, 
facilitates the development of an evolving system. ICE-80 and ICE-85 include some 
debugging features, and also permit the use of Intellec memory in place of part or all 
of the iSBC 80 physical RAM and/or ROM (memory mapping facility). The 
RMX/80 software package also includes a Debugger, described in Chapter 6, which 
is especially designed for real-time systems based on RMX/80. You may wish to 
configure the Debugger in your system during development, then delete it when the 
rest of the system is fully tested. 




Hardware Components 

Design of a microcomputer system using iSBC hardware is outside the scope of this 
manual. It is sufficient here to make a few general comments, and to mention some 
constraints and considerations related to accommodating hardware design to 
RMX/80 software. 

Requirements. Certain special installation procedures must be followed when using 
an Intel terminal, ICE-80 or ICE-85, and/or the RMX/80 Demonstration System 
program on an iSBC system. These procedures are given in Appendix F, "Hardware 
Considerations." 

The RMX/80 Nucleus has certain hardware requirements, which are listed in 
Chapter 2. Hardware requirements for RMX/80 extensions are given in the chapters 
on those extensions. You also need to estimate the I/O, interrupt, and memory re- 
quirements for your application tasks. Refer to "Planning Memory Space" later in 
this section for further discussion of memory requirements. 



Software Components 

Your RMX/80 application will consist of the RMX/80 Nucleus (always required) 
and two main categories of tasks — those selected from the RMX/80 software 
package and those supplied by you, the user, for your particular needs. 



RMX/80 Extension Tasks. You will probably want to select these first. Most 
RMX/80 extensions provide several tasks, from which you may choose those you 
need for your application. RMX/80 extensions are covered in later chapters of this 
manual (Chapter 4 and all the following chapters); refer to these chapters for func- 
tional descriptions of the tasks. Appendix D provides a complete list of RMX/80 ex- 
tension tasks and the memory requirements for each. 

User Tasks. Breaking down your application into tasks is an extremely important 
part of the system design process, and should be done with care. In general, it is bet- 
ter to have a number of smaller tasks rather than a few very large tasks, in order to 
minimize system idle time. However, the number of tasks should not be too great, 
either. Too many tasks add needless complexity to the system, making it difficult to 
modify or debug, and also add to system overhead. In general, tasks should be 
allocated to performing functions and servicing events. 

Another general rule to follow is that high-priority tasks, including those that service 
interrupts, should be as short as possible. To understand the reason for this rule, 
consider a task that performs a number of lengthy calculations and is invoked by a 
high-priority interrupt. As long as this task is running, no lower-priority interrupt 
can be serviced, and no lower-priority task can be run. The case of lower-priority in- 
terrupts is especially troublesome, since it is possible that some interrupts might be 
missed altogether. A reasonable solution to this problem is to divide the task into 
two smaller tasks. The first task services the interrupt as quickly as possible and then 
sends the input data (in the form of a message) to a second task. The second task, 
which may have a much lower priority, can then process the data, allowing other in- 
terrupts to be serviced and other tasks to compete for the processor. 

Exchanges. After defining your tasks, you must determine the exchanges you need 
for intertask communication. To the exchanges required for the RMX/80 exten- 
sions, you add those you define yourself for the needs of your own tasks. There is 
generally some freedom of choice in defining the number of exchanges; some tasks 
may be able to share an exchange, and others may operate more efficiently with 
dedicated exchanges. Later, when you test your system, you may want to alter your 
exchange configuration to improve system performance. 
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Once you have selected your tasks and exchanges, it is helpful to make a system 
diagram showing task-exchange relationships. (For examples, see the exchange 
diagrams near the beginning of Chapters 4 through 8, and also figures J-2 and J-3 in 
Appendix J.) 

Planning Memory Space 

As shown in figure 2-8 at the end of Chapter 2, several types of code and data 
segments must be allocated memory space in an RMX/80 application system. These 
segments may be summarized as follows: 

ROM segment: 

• RMX/80 Nucleus code 

• Initialization structures required by the Nucleus (Create Table, Initial Task 
Table, and Initial Exchange Table) 

• Code for RMX/80 extension tasks 

• Code for user application tasks 
RAM segment: 

• Data area required by RMX/80 Nucleus (for list pointers, system messages, 
etc.) 

• Task Descriptors and Exchange Descriptors 

• Stack, initial program counter, and miscellaneous data required by user 
application tasks in the system (including messages) 

As explained in the footnote on figure 2-8, these sections of code and data need not 
be located in the particular address spaces or sequence shown in the diagram. The 
only constraints are that the RMX/80 ST>^RT module (which is the main program 
module in any RMX/80 application system) be located at address OH, or address 
40H or higher. In the later case, RESET will not restart the system unless user code 
at location OH transfers control to the Nucleus START module. The first section of 
RAM must be located at the address determined by the hardware configuration 
(refer to "Linking and Locating" later in this chapter.) 

It is important to remember that when an RMX/80 system is set up to be self-in- 
itializing without the use of peripheral loading devices, all information in the initial 
configuration must be in ROM. This means that any constants to be stored initially 
in RAM must be provided in ROM, along with the code to store them in RAM after 
the program is started. PL/M INITIAL declarations and initial values specified in 
assembler DSEG directives have no meaning in such a system unless RAM is loaded 
from an external device. 

Appendix D lists the memory requirements in bytes for RMX/80 Nucleus and exten- 
sion task code and data, and for system structures in ROM and RAM. Note that 
future enhancements to RMX/80 may result in changes to the exact numbers of 
bytes required. 

Some RMX/80 extensions impose special memory requirements. For example, the 
Disk File System tasks require a certain amount of controller-addressable RAM, 
which for iSBC 80/20 and 80/10 systems must be located off the main CPU board 
(so that it is accessible to the bus). Refer to the chapters on the individual extensions 
you are using for any special requirements. 

Coding User Tasks 

General System Structure 

An RMX/80 application system consists of a main program module (the RMX/80 
START module) and an arbitrary number of independent tasks that run under the 
control of the main module. The main module and any of the tasks may call pro- 
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cedures or subroutines in a nested fashion, subject to the constraints of the program- 
ming language and RAM space available for stacks. User-supplied application tasks 
and RMX/80 extension tasks are treated identically by RMX/80. 

It is important to recognize the difference between a task and a procedure (PL/M) 
or subroutine (assembly language). A task is scheduled for execution by RMX/80 
and may run concurrently with other tasks. A procedure or subroutine is called by 
the RMX/80 main program module, by a task, or by another procedure or 
subroutine, and gains control immediately when it is called. A task is invoked by the 
RMX/80 scheduling software; a procedure or subroutine is invoked by an 8080 or 
8085 CALL instruction. 

Another crucial difference between a task and a procedure or subroutine is that a 
procedure or subroutine may be thought of as a section of code, whereas a task can- 
not always be visualized this way. A task is defined by its Static Task Descriptor, 
which gives a starting address for code. It is possible for several tasks to run with the 
same section of code, if that code is made reentrant. (See "Code Shared by More 
Than One Task" later in this section.) 

Unlike a procedure or subroutine, each RMX/80 task requires a separate stack for 
context saves; there is no system stack. Your task may also use its stack for its own 
processing. RMX/80 performs all context saves for tasks. However, if you wish to 
supply your own interrupt service routines (as described under "Interrupt Handl- 
ing" in Chapter 2), these routines must perform a context save on entry and a con- 
text restore on exit. 



Parameter Passing and Returned Values 

All RMX/80 operations follow the PL/M parameter passing conventions. For this 
reason, and also because you may wish to code some of your application software in 
PL/M and some in assembly language, it is well to note the parameter passing con- 
ventions followed by PL/M. If there is one parameter, it is passed in the B and C 
registers if it is an address value, or in the C register if it is a byte value. If there are 
two parameters, the first is passed in the B and C register pair. The second 
parameter is passed in the D and E registers if it is an address value, or the E register 
if it is a byte value. If there are more than two parameters, the first n-2 are passed on 
the stack (earlier parameters are pushed first) and the last two are passed in the BC 
and DE register pairs. 

If a procedure returns an address value, it is returned in the H and L register pair. If 
the procedure returns a byte value, it is returned in the accumulator. 

Public and External Symbols 

To establish linkage among tasks and RMX/80 software, the modules that contain 
code for the tasks must declare certain public and external symbols. For example, 
the address of Exchange Descriptors must be declared PUBLIC by the program 
module where they are defined and EXTERNAL (EXTRN in assembly language) by 
any other modules that reference them. Appendix B supplies a list of all RMX/80- 
defined PUBLIC and EXTERNAL symbols with which your tasks may need to in- 
terface. 



Names 

Names of variables and procedures or subroutines in user tasks may be any names 
permitted by the programming language, except that no names should have a "Q" 
or "?" in the second position. Names beginning with "RQ" are reserved for 
RMX/80 identifiers. 
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Programming Aids 

The RMX/80 diskettes provide a number of "INCLUDE files" — i.e., files contain- 
ing PL/M or assembly-language code commonly needed in user tasks. Rather than 
write out the code yourself wherever you need it in your program, you can simply 
name the appropriate file in an assembler or PL/M compiler SINCLUDE control, 
and the code will be inserted in your program. Appendix A lists the names of all IN- 
CLUDE files on the diskettes and indicates the contents of each. To make sure the 
names you reference elsewhere in your tasks match those in the INCLUDE files you 
use, it is advisable for you to make listings of these files ahead of time. 

Initialization 

Tasks are typically coded as an endless loop preceded by a segment of initialization 
code. The initialization code is usually specific to the individual task and includes 
functions such as initializing counters. Instead of having each task perform its own 
initialization, you may prefer to code one task to perform the initialization for all 
other tasks. However, this scheme may involve the declaration of a large number of 
public symbols, which may prove cumbersome, especially when several program- 
mers are coding individual tasks for the system. 

Code Shared by More than One Task 

As discussed earlier, it is possible for seveial tasks to share the same section of code, 
if that code is made reentrant. (Reentrant code keeps all variable data in registers 
and/or on the stack. See the PL/M-80 Programming Manual for details.) Informa- 
tion (such as display messages) that differs from task to task can be supplied in a 
message sent to invoke the task. 

To accomplish this, you specify (in the configuration module or via RQCTSK opera- 
tions) a different Static Task Descriptor for each task, but assign the same Initial 
Program Counter value in each Static Task Descriptor. (This cannot be done if you 
use the assembly language STD macro.) If you are creating the tasks dynamically, 
an alternative method is to use a single Static Task Descriptor in RAM and modify 
the TASK POINTER and STACK ADDRESS fields of the Static Task Descriptor 
before each call to RQCTSK. 

In addition, each of the tasks sharing the same code may need to wait for a message 
at its own unique exchange. The shared cc de can accomplish this by using the default 
exchange feature of the RQWAIT or RQACPT operation. If RQWAIT or RQACPT 
is called with an exchange address of zero, the task waits at the default exchange 
specified in the EXCHANGE ADDRESS field of the Task Descriptor. 

There is, however, one set of circumstance s under which this technique for providing 
unique exchanges fails. Suppose that three tasks (called A, B and C) share a code 
segment. Further suppose that this common code segment causes each task to wait 
at two exchanges, and that the first exchange at which each task waits is intended 
to be distinct from the exchanges at whicii the other two tasks wait. In other words, 
task A waits at exchange 1, task B at exchange 2, and task C at exchange 3. Also 
suppose that the second exchange at which each task waits (exchange 4) is common 
to all three tasks. Using the default exch ange technique described in the preceding 
paragraph, each task will initially wait at the proper exchange. However, once a 
task waits at exchange 4, the default exc hange address associated with that task is 
modified by RMX/80 to point to this most recently used exchange. Consequently, 
each task loses access to its unique exchange. 

The default exchange technique can still De used if the following precaution is taken. 
Before waiting at the common exchange, the shared code segment must extract the 
address of the default (unique) exchange from the Task Descriptor of the running 
task (referenced by RQACTV). This address should then be stored in local storage. 
After the shared code segment has caused the task to wait at the common exchange, 
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the address of the unique exchange should be retrieved from local storage and stored 
back into the Task Descriptor. This process, although cumbersome, will preserve 
the uniqueness of unshared exchanges. 

Messages 

RMX/80 imposes certain format requirements on all messages in the application 
system. These are described in Chapter 2 under "Message Coding." More specific 
requirements for particular types of messages sent to RMX/80 extension tasks are 
given in the chapters on the RMX/80 extensions. 

When a task sends a message via an RQSEND operation, what is sent is the address 
of the first byte of the message. In PL/M, you may use this address as a base and 
treat the message as a based variable. If you are programming in assembly language, 
you will find this address in the H and L registers, which can be incremented to ac- 
cess the other fields of the message. 

Once it is sent, a message is intended to be the exclusive property of the task that 
receives it; neither the sending task nor any other task should alter or resend it. After 
the receiving task is finished with the message, it may send it back to the originating 
task or to another task. By convention, this is done using the RESPONSE EX- 
CHANGE or HOME EXCHANGE fields of the message. 

Interrupts 

Application tasks should not directly execute 8080 EI and DI instructions. If the task 
needs to disable a particular interrupt on the iSBC 80/20, 80/24 or 80/30, RQDLVL 
should be used; RQELVL should be used to re-enable it. In an iSBC 80/ 10A or 
80/ 10B version of RMX/80, the priority of the running task determines whether the 
single hardware interrupt level is enabled or disabled. (Refer to "iSBC 80/10 
Interrupts" in Chapter 2.) 

Exclusive Access to Code 

When an application task requires exclusive access to a section of code, locking out 
even tasks of higher priority that need to use it, a software lock can be programmed 
using the RQSEND and RQWAIT operations. 

For example, assume that a system contains a non-reentrant software divide routine. 
Because this can be a lengthy routine, only one copy of it exists in the system, and it 
is shared by all tasks. Because the RAM buffers must not be altered by a second user 
during the division, it becomes necessary to block access to the division routine. The 
routine may be preempted and restarted, but no other user can be allowed to use the 
routine. The lock can be implemented as follows: 

/•TASK INITIALIZATION CODE*/ 

■ 

CALL RQSEND(.LOCKEX,.LOCK); 
/♦END OF INITIALIZATION CODE*/ 

/•DIVIDE ROUTINE*/ 
GO=RQWAIT(.LOCKEX,0); 

/•INSERT DIVISION ROUTINE CODING HERE*/ \ protected code 



CALL RQSEND(.LOCKEX.GO); 

The first task that attempts to use the divide routine will be able to do so, since there 
is a single message waiting at the LOCKEX exchange as a result of the task initializa- 
tion code. However, as soon as this first task begins executing the division routine, it 
also removes the message from the LOCKEX exchange. This ensures that the task 
retains control of the division routine and thus protects its RAM buffers until the 
division is complete. At this point, the LOCK message is sent back to the LOCKEX 
exchange to enable another task to obtain access to the routine. 
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Generating The Software Configuration 

After defining and coding your own tasks, you specify the configuration of your 
system by means of the Interactive Configuration Utility. Before using the ICU80 
utility, you must make several decisions: 

• What tasks are to be included in the system, and what are the characteristics of 
these tasks (priorities, etc.)? 

• What exchanges are to be defined when the system is initialized? 

• What are the characteristics of each disk controller in the system? 

• What are the characteristics of each disk drive in the system? 

• How are Disk File System buffers to be allocated? 

Tasks. For each task in the initial configuration, you must specify a name, the initial 
program counter, the stack length, the priority, and the default exchange. 

Each task must be given a NAME consisting of any six ASCII characters. For 
RMX/80 extension and disk controller tasks, use the names furnished in the ap- 
propriate RMX/80 extension chapters. User tasks may be given any convenient 
names, except that these names should not have a "Q" or "?" as the second 
character. 

The INITIAL PROGRAM COUNTER for a task is its entry point address, general- 
ly given as a symbolic value. 

The maximum STACK LENGTH for a ta sk is determined by several factors, which 
are discussed further below under "Estimating Stack Length." 

You must assign a software PRIORITY level between 1 and 254 to each user and 
RMX/80 extension task. Rules and suggestions for assigning priorities are given 
below under "Assigning Priority Levels." 

The DEFAULT EXCHANGE is optional for user tasks. RMX/80 places this data in 
the EXCHANGE ADDRESS field of the Task Descriptor it builds when the system 
is initialized. 

Estimating Stack Length. The maximum stack length for a task is a function of the 
level of nesting which occurs within the task. It also must include space for any 
miscellaneous data the user task pushes on the stack and 48 extra bytes for use by the 
RMX/80 scheduling algorithms. A rough estimate of stack length in bytes may be 
obtained by the following formula: 

St = 48 + 1.10 (Su) 

where St is the approximate stack length required for the task; Su is the compiler-or 
assembler-generated stack requirement user task, including the user-supplied pro- 
cedures or subroutines and the RMX/80 procedures that it calls. The 48 extra bytes 
are required for RMX/80 interrupt handling, and the 1.10 multiplier serves as an 
error factor. If desired, a larger and therefore more conservative multiplier can be 
used. 

Stack lengths required for RMX/80 extension tasks and Nucleus operations are sup- 
plied in Appendix D. 

Another approach for determining task stack length is to start with a grossly 
overestimated value (considerably larger than the value found by the formula 
above), and then to use the RMX/80 Debugger FORMAT TASK command (see 
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Chapter 6) to determine the amount of stack space left after testing it under worst- 
case conditions. After subtracting 48 from this value to account for the fact that the 
task may not have been interrupted, the stack allocation can be correspondingly 
reduced. 

Assigning Priority Levels. RMX/80 provides 256 software priority levels; of these, 
254 are available to the user. (Level is used by the Debugger scan and exchange 
breakpoint facilities; level 255 is reserved for the idle task.) 

Priority levels 1 through 128 correspond to specific interrupt levels, as shown in 
table 2-2 in Chapter 2. These priorities should generally be reserved for interrupt ser- 
vice tasks, with the devices of highest speed running at the highest interrupt levels 
(lowest level numbers) with service tasks given corresponding software priorities. 
Tasks that do not service interrupts should generally be assigned priorities 129 
through 254. An exception to this may occur when background calculations for a 
high priority device are more important than handling interrupts from a very low 
priority device. In this case the background task should have a priority that is higher 
than the interrupt task for the low priority device. 

In general, emergency tasks should have higher (lower-numbered) priorities than 
routine operations; quickly finished operations should have higher priorities than 
longer operations; and tasks requiring rapid response should have higher priorities 
than those that are not so urgent. During testing of the system, it may become ap- 
parent that certain tasks are running too frequently or not frequently enough. In 
such cases, reconfiguring the system with different priorities for these tasks may cor- 
rect the problem. 



Linking and Locating 

After using the Interactive Configuration Utility, you must SUBMIT the file that is 
the result of configuring. That file performs the necessary linking and locating, 
resulting in an absolutely located system. 

NOTE 

You can generally save time by configuring tasks/ modules into the system 
one by one rather than all at once. During testing and debugging, you 
may wish to configure tasks/ modules into the system as they are 
debugged. 

If your code includes a subroutine shared by several tasks, you must either make it 
reentrant or supply a separate copy for each task. An easy way to do the latter is to 
link the subroutine separately to each of the tasks that calls it. 



Locating. 

The starting address for code in most RMX/80 systems is specified as zero. Also, the 
stack size is specified as zero, since each task has its own stack. 

The default starting address for the data segment is 3800H for on-board RAM on the 
iSBC 80/20. This default starting address is 3000H for the iSBC 80/20-4 and 80/24; 
6000H for the iSBC 80/30; and 3C00H for the iSBC 80/ 10A and 80/10B. 

On the iSBC 80/20, 80/20-4, 80/24, and 80/30, the starting address can be re-wired 
to one of several other values. You will find it necessary to modify the RAM starting 
address if the size of your code segment (which is typically in ROM) exceeds the 
default starting address. Alternatively, you may elect to use some other RAM 
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starting address if your application's RAM requirements exceed the amount of RAM 
storage on your iSBC 80. 

NOTE 

RMX/80 uses the following Absolute memory locations for Restart 
Vectors, provided that you specify to the Interactive Configuration Utility 
that interrupts will be used: 

80/30 80/20 80/ 10A and 80/ 10B 

24H - 2EH 28H - 2 AH 28H - 2AH 

34H - 36H 38H - 3 AH 

3CH - 3EH 3BH - 40H 

The locations for the iSBC 80/24 are usually the same as those for the iSBC 80/20. 
However, if an application uses any of the 8085 on-chip interrupts, the locations for 
the iSBC 80/24 are the same as those for the iSBC 80/30. 

Locations 28H - 2AH are used by the Active Debugger for Execution Breakpoints. 
Other locations are for Interrupt Restart Vectors. 

Your RMX-based system will normally be LOCATED beginning at memory loca- 
tion 0000, and the LOCATER will issue warnings of memory conflicts at the Restart 
Locations. RMX has allowed space for this in its code and the messages can be ig- 
nored. 

If you choose not to LOCATE at zero, you should LOCATE at 41 H or higher and no 
other code should use the memory locations mentioned above. You must also 
provide code at location 0000 to transfer control to the RMX/80 START module 
when the system is RESET. 

Unresolved External References 

The RMX/80 Nucleus resolves all references to interrupt exchanges. 



Testing and Debugging 

The Intellec microcomputer development system, with its ICE-80 and ICE-85 op- 
tions, provides a convenient means for testing and debugging your RMX/80 ap- 
plication system. The features of this system are covered in the set of manuals listed 
in the Preface to this manual. 

However, the unique operational structure of a real-time system makes certain addi- 
tional debugging features worthwhile. The RMX/80 Debugger, especially tailored 
for systems based on RMX/80, provides such features. Chapter 6 supplies complete 
instructions and suggestions for using the Debugger to test and debug your applica- 
tion system. 
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General Description 

The Terminal Handler provides real-time asynchronous I/O between an operator's 
terminal and tasks running under the RMX/80 Nucleus. The Terminal Handler pro- 
vides a line-edit capability similar to that of ISIS-II (see ISIS-II User's Guide, order 
number 9800306) and an additional type-ahead feature. The type-ahead feature 
allows the terminal operator to enter (or continue entering) up to 63 characters (with 
no echo) even when there is no current request for input. 

The Terminal Handler completely relieves u ser tasks from the duties required to per- 
form physical I/O with a terminal. Instead, user tasks perform input at the level of a 
logical line, taking input data from the Terminal Handler's line buffer. Output may 
be at the level of a single character, a logical line, or a set of lines. 

The line-edit feature assures the user task of receiving relatively "clean" input from 
the terminal. For example, by using the RL BOUT control, the operator can correct 
a typing error before it is passed to the user task. In addition, the Terminal Handler 
output display (printout on a Teletypewriter) provides an echo of all input 
characters entered in the line buffer. 

Variations 

There are three separate versions of the Temiinal Handler, one for the iSBC 80/20 
and 80/24, one for the iSBC 80/30, and one for iSBC 80/ 10A and 80/ 10B. Addi- 
tionally, each version can be configured foi either input-output or output only, and 
for either the full Terminal Handler or the riinimal Terminal Handler. The principal 
differences between these configurations are displayed in a table at the end of this 
chapter. 



Use Environment 

The Terminal Handler (in any of its configurations) is designed to accommodate a 
variety of different terminal models. Terminals may be of the CRT display or 
teletypewriter design with baud rates ranging from 110 to 9600, asynchronous. 
Notice, however, that the Terminal Handle - directly supports only one terminal in a 
system. The Terminal Handler supports a maximum input line length of 132 
characters. 



Memory and Hardware Requirements 

Memory requirements range from approximately 3000 bytes of code space and 900 
bytes of data space for the full input-outpul Terminal Handler to less then 200 bytes 
of code space and 100 bytes or less of data space for the minimal output-only Ter- 
minal Handler. Refer to Appendix D for exact byte counts. 

The Terminal Handler uses interrupt level (> for input and 7 for output. In the iSBC 
80/20, 80/24 and 80/30 versions, these interrupts are routed through the 8259 
Programmable Interrupt Controller. In the iSBC 80/ 10 versions, the RMX/80 soft- 
ware pseudo-interrupt levels are used. The interrupts originate in the 8251 
Programmable Communications Interface (US ART), which is used for all I/O on 
the iSBC 80. 
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In the iSBC 80/10 versions, the Terminal Handler supplies the interrupt polling 
routines for input and output and the RQSETP calls to set them up, so that the user 
task need not be concerned with these routines. Pseudo-interrupt level 6 is used for 
input, and level 7 for output. 

On the iSBC 80/20, 80/24, or 80/30, the full Terminal Handler can provide an 
optional automatic baud rate search. (This option is described under "Using the 
Terminal Handler" later in the chapter.) On the iSBC 80/20, 80/24, and 80/30, the 
Terminal Handler uses Counter 2 of the 8253 Interval Timer to generate baud rate 
timing for the 8251 US ART. 



How the Terminal Handler Operates 

Input and Output 

A logical line is a series of characters terminated by a break sequence. In the full Ter- 
minal Handler, a break sequence may be an Escape character (ESC), a Line Feed 
character (LF), or the sequence Carriage Return-Line Feed (CR,LF). In the minimal 
Terminal Handler, the only break character is a Carriage Return (CR). The Ter- 
minal Handler automatically generates a Line Feed after a Carriage Return. 
However, if a Carriage Return happens to fill the last (132nd) buffer position, there 
will be no room to generate the Line Feed. The Terminal Handler recognizes a break 
sequence in this situation; application tasks that process the input lines should be 
programmed to take this possibility into account. 

Input operations are normally performed one logical line at a time. When a user task 
is ready to accept input, it sends a read request message to the Terminal Handler. 
This message tells the Terminal Handler the buffer address where it is to place the in- 
put data and the number of characters the user task is prepared to receive. The Ter- 
minal Handler responds by moving the specified number of characters from the cur- 
rent logical line into the user buffer. 

The minimal Terminal Handler will accept enough input characters to fill the cur- 
rent outstanding read request (or until a carriage return). If the current read request 
is filled before a carriage return is input, the minimal Terminal Handler issues a BEL 
character and accepts no more input until the next read request. 

The full Terminal Handler will accept enough input characters to fill the current 
outstanding read request (or until a break sequence), plus the 63 characters it will ac- 
cept into its type-ahead buffer. When the type-ahead buffer is full, the Terminal 
Handler will output a BEL character and accept no more input until the type-ahead 
buffer is cleared by a read request. A requesting task does not need to accept the en- 
tire logical line at one time. For example, the task might read only five characters of 
the logical line at a time. (This technique can be used to conserve RAM.) The task 
can detect the end of a line by checking for the break sequence. 

In both minimal and full input-output versions, the Terminal Handler indicates the 
completion of the read operation by returning the read request message with a field 
that indicates the actual number of characters placed in the user buffer. This is 
helpful when the logical line does not contain enough characters to satisfy the count 
requested for the read. 

To write a logical line to the terminal, the user task first builds the desired line in a 
RAM buffer. The task then sends a write request message to the Terminal Handler. 
This message tells the Terminal Handler the length and address of the output line. 
To the user task, the output operation appears complete at this point. However, the 
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Terminal Handler must still perform the physical output. Completion of physical 
output is indicated by returning the write request message with a status code to let 
the task know whether the operation is successful. The user task must not attempt to 
build another output line in the same RAM locations until the output operation is 
complete. You may, of course, initiate output operations from other RAM locations 
before the preceding operations are complete. 



Line Editing 

As an operator enters keystrokes (provided a read request message is available at the 
Terminal Handler input exchange) the corresponding characters are placed in the 
Terminal Handler's line (input) buffer. Th<; Terminal Handler then echoes a copy of 
each character back to the terminal. (Hcwever, echo output must be enabled as 
described under "Read Request Message" later in this section.) Remember that the 
terminal is both an input and an output device. Each keystroke is an input to the 
system. Any character displayed on the terminal is an output from the system. In 
most cases, the echo is returned to the terminal so quickly that the operator is not 
aware that the keystroke does not directly effect the display line. 

If no read request message is currently available, none of the preceding steps takes 
place. In the full Terminal Handler, up to 63 characters are stored in the type-ahead 
buffer. When a read request message becomes available, the characters are trans- 
ferred from the type-ahead buffer to the line buffer, and the echo is then performed. 
However, the minimal Terminal Handler has no type-ahead buffer; so when the 
minimal Terminal Handler is used, characters that are input when there is no read 
request message are simply lost. 

Because of error corrections, there is not a . ways a direct correspondence between the 
contents of the Terminal Handler's input buffer and the terminal's display line. For 
example, RUBOUT causes the Terminal Handler to delete the previous character 
from its input buffer. At the same time, the Terminal Handler echoes a second copy 
of the character to the display to assure the operator that the correction has actually 
occurred. The following example illustrates the difference between the display and 
the input buffer. Assume that the operator enters TARFET and corrects it to 
TARGET using three RUBOUTs: 

DISPLAY LINE: TARFETTEFGET 
INPUT BUFFER: TARGET 

(The control-R command, described lat;r in this chapter, may be used by the 
operator to generate a clean copy of the input buffer.) Maintaining both the input 
buffer and the terminal display are two more services provided by the Terminal 
Handler. 



Terminal Handler Exchanges 

NOTE 

In what follows, there are numerous references to RQALRM, 
RQDBUG, and the Debugger. The reader should bear in mind that these 
features are not operative on the minimal Terminal Handler. 

Figure 4-1 graphically illustrates the relat onships between a user task and the Ter- 
minal Handler. The illustration is simplified for clarity. 
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Figure 4-1 . Terminal Handler Exchanges for Full Input-Output Versions 



Circles represent exchanges. Although the RQINPX and RQOUTX exchanges are 
the primary user task interfaces with the Terminal Handler, an additional high- 
priority output exchange is also provided in the full Terminal Handler. The 
RQALRM exchange functions the same as the RQOUTX exchange, with two excep- 
tions: its priority is higher, and output to it cannot be blocked by the control-S com- 
mand (see "Output Controls" later in this chapter). Also, the RQALRM exchange 
can optionally generate an alarm message line before it displays the user output. The 
alarm message is displayed as follows: 



ALARM 



The alarm message also sends two BEL characters to the terminal. The BEL 
characters sound the terminal's audible alarm, if it has one. Notice that output 
messages may be queued at both the RQALRM and RQOUTX exchanges. Since the 
RQALRM exchange has the higher priority, alarm messages are always displayed 
before all other output, including echo output. (This can cause echo characters to be 
interspersed with a message coming out from RQALRM.) Also, remember that, all 
messages sent to an exchange are processed on a first-in/first-out basis. 



NOTE 

Since RQALRM has the higher priority, it will preempt a display in pro- 
gress through RQOUTX. 



Debugger Exchanges 

Two additional exchanges, illustrated in figure 4-2, provide an interface between the 
Terminal Handler and the RMX/80 Debugger (described in Chapter 6). The first of 
these is the RQWAKE exchange, which is used to invoke the Debugger. A message 
of type CNTRLSCSTYPE is sent to this exchange only when the operator enters a 
control-C command. 
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DEBUGGER 



Figure 4-2. Termii 



In a system that includes the Debugger, the control-C causes the following opera- 
tions to occur: 



• The Debugger is activated. 

• The RQINPX exchange is locked out and remains locked out until the Debugger 
is exited via the QUIT (Q) command. While the Debugger is active, all input is 
directed to the Debugger and is subject to the Debugger's input conventions. 

• The Debugger instructs the Terminal Handler to clear any residual data 
remaining in its buffers. 



• The Debugger outputs a prompt character via the Terminal Handler. 

In a system configured without the Debugger, entering a control-C causes a message 
to be sent to the RQWAKE exchange. Such a system has no built-in response to this 
message, thus allowing you to use it for your own purposes. 



Because the RQINPX exchange is locked out while the Debugger is active, the 
RQDBUG exchange is provided for Debugger input. 

NOTE 

The direction of the arrows indicates the direction of messages sent to 
and received from exchanges. Response exchanges are not shown. 



Notice that the Debugger uses the Terming! Handler's high-priority RQALRM ex- 
change for output. Although the Debugger blocks normal input by locking the 
RQINPX exchange, the RQOUTX and RQALRM exchanges continue to operate 
normally. If desired, the operator can block output via RQOUTX with a control-S 
command. RQALRM exchange output cannot be blocked, since the Debugger re- 
quires use of this exchange. 
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Using the Terminal Handler 

The Terminal Handler differs from other RMX/80 extensions in that it involves both 
a programming interface and an operator interface. These two concerns overlap 
when the optional baud rate search (available on the full input-output Terminal 
Handler for the iSBC 80/20, 80/24, or 80/30) is used. The primary programming 
interface between user tasks and the Terminal Handler is via read and write request 
messages. For the operator interface, the input-output versions of the Terminal 
Handler supply a set of one-character control commands. 



Read and Write Request Messages 

Tasks communicate with the Terminal Handler by means of two types of messages: 
read request and write request. A read request message consists of a standard 
RMX/80 message heading and the REMAINDER portion that is similar to an ISIS- 
II READ system call. Likewise, the write request message has a REMAINDER 
portion similar to an ISISTI WRITE system call. A read or write operation is 
performed by sending a request message to the appropriate exchange, as described 
in the following sections. Standard PL/M declarations of Terminal Handler 
messages can be obtained by using the INCLUDE file THMSG.ELT. 



Read Request Message. The read request message is generally sent to the RQINPX 
exchange, although in some cases it may be sent to RQDBUG (see description of 
TYPE field for this message). The read request message performs two important 
functions: 

• It initiates the transfer of input characters from the type-ahead buffer into the 
Terminal Handler's line buffer. (Remember that the minimal Terminal Handler 
has no type-ahead buffer.) This function is especially important because input 
data is echoed back to the terminal's display only from the line buffer. 
Characters are not placed in the line buffer unless there is an outstanding read 
request. This deferred echoing can be quite useful, since it allows the operator to 
continue entering data while data is being written to the display. However, it can 
be confusing for an operator to make a lengthy "blind" entry (one that is not 
echoed within a reasonable time). To prevent such delays, it is advisable that a 
task which requests input wait immediately thereafter at the appropriate 
response exchange. 

• It signals the Terminal Handler that the user task is ready to accept data. 
However, before releasing any data into the user task's buffer, the Terminal 
Handler waits until it has a complete logical line or until all 132 characters of its 
line buffer are filled. The Terminal Handler forces a break sequence when the 
line buffer is filled so that subsequent data is not lost. 

When the Terminal Handler has processed the request, it returns the read request 
message with a status code that indicates either successful completion of the 
transfer, or an unacceptable message type. 

The format of the read request message is shown in figure 4-3. Asterisks denote 
fields that must be coded by the user task before the message is sent. Shaded fields 
are those set or changed by the Terminal Handler when it returns the message. 

Those fields that have specific meanings in the read request message are described in 
the following paragraphs. (For general information, refer to "Message Coding" in 
Chapter 2.) 



4-6 



RMX/80 



Terminal Handler 



LENGTH is 17. 

In the full Terminal Handler, TYPE must be one of the following types: 
READSTYPE (8), CLRSRDSTYPE (9), or LASTSRDSTYPE (10). In the minimal 
Terminal Handler, READSTYPE must be used. 

• READSTYPE is the most commonly used type of read request. In the full 
Terminal Handler, it allows a read jsing type-ahead. When directed to the 
RQDBUG exchange, this type has the additional function of locking out the 
RQINPX exchange, enabling you to send input to the Debugger via the 
RQDBUG exchange without the risk that the input will be interpreted as data by 
the executing task. 

• CLRSRDSTYPE clears any type-ahead and then reads. This is useful when an 
emergency interrupt question is directed to the terminal (and an immediate 
response is expected). Since this event is unpredictable, there could be unwanted 
data in the type-ahead buffer, and this data would be treated as a response to 
the question. CLRSRDSTYPE insures that the type-ahead buffer is emptied so 
that you are sure you get the desired response rather than any residual type- 
ahead data. Use of the RQDBUG exchange with this message type should be 
considered reserved for the Debugger u nless you are writing your own debugging 
or other high-priority routine. 

• LASTSRDSTYPE allows a read using type-ahead. When directed to the 
RQDBUG exchange, this type has the additional function of unlocking the 
RQINPX exchange. This type should be considered reserved for the Debugger 
unless you are writing a debugging routine of your own. When directed to the 
RQINPX exchange, LASTSRDSTYPE functions the same as READSTYPE. 

HOME EXCHANGE is not used by the Terminal Handler. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange 
where the requesting task waits for a response from the Terminal Handler. 

When the Terminal Handler returns this message, it sets STATUS to to indicate 
normal completion of the read. STATUS is set to BADSCOMMAND (18) if the user 
specified a message type other than READSTYPE, CLRSRDSTYPE, or 
LASTSRDSTYPE (if other than READSTYPE, in the case of the minimal Terminal 
Handler). In this case, no data is transferred from the line buffer to the user buffer. 
The read request must be re-issued to correct this non-fatal error. ACTUAL is 
undefined when an error message is returned. 

BUFFER ADDRESS must specify the RAM address where the Terminal Handler is 
to store the data resulting from the read request. Break sequence characters are con- 
sidered part of the data and are placed in tiie buffer. 

COUNT must specify the number of cha acters to be read. The maximum value is 
132. 





2 
4 
S 
7 
9 
11 
13 
15 



LINK 



HOME EXCHANGE 



RESPONSE EXCHANGE* 



STA rus 



BUFFER ADDRESS" 



Figure 4-3. Read Request Message 
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In ACTUAL, the Terminal Handler supplies the actual number of characters 
transferred from the line buffer to the user buffer when it returns the request 
message to indicate completion of the read. This value will be less that the COUNT 
field when the line buffer does not contain enough characters to fill the user buffer. 
Characters located in the buffer beyond BUFFER ADDRESS + ACTUAL should 
be considered undefined. 



Write Request Message. The write request message is sent to either the RQOUTX 
exchange or the RQALRM exchange. (See description of TYPE field for this 
message.) This message initiates a transfer of data from the user task's buffer to the 
terminal. The Terminal Handler returns the write request message with a status code 
that indicates either successful completion of the transfer, or an unacceptable 
message type. 

The format of the write request message is shown in figure 4-4. Asterisks denote 
fields that must be coded by the user task before the message is sent. Shaded fields 
are those set or changed by the Terminal Handler when it returns the message. 

Those fields that have specific meanings in the write request message are described in 
the following paragraphs. (For general information, refer to "Message Coding" in 
Chapter 2.) 



LENGTH is 17. 

In the full Terminal 
ALARMSTYPE (11). In the 
used. 



TYPE must be either WRITESTYPE (12) or 
Terminal Handler, WRITESTYPE must be 



• WRITESTYPE directs the Terminal Handler to write out the specified bytes. 
This type is valid for either the RQOUTX or RQALRM exchange. 

• ALARMSTYPE causes the Terminal Handler to write an alarm message (CR, 
LF, *, BEL, *, BEL, * ALARM, CR, LF) followed by the specified bytes. This 
type is valid only for the RQALRM exchange. (Recall that in the minimal Ter- 
minal Handler, RQALRM does not exist.) 

Note that both WRITE$TYPE and ALARMSTYPE are valid for the RQALRM 
exchange. This allows you to write a single alarm message followed by a number 
of lines of text rather than have an alarm message before each line. Remember that 
output to the RQALRM exchange has priority over output to the RQOUTX exchange. 
ALARM$TYPE is not valid for RQOUTX. The RQALARM output will not be 
written to the terminal, however, until any RQOUTX message in progresss has been 
completed. 






LINK 


2 


LENGTH' 


4 


TYPE* | 


S 


HOME EXCHANGE 
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RESPONSE EXCHANGE* 
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STAT JS 
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BUFFER ADDRESS* 


13 


COUNT* 
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Figure 4-4. Write Request Message 
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RESPONSE EXCHANGE must specify the address of the user-defined exchange 
where the requesting task waits for a response from the Terminal Handler. 

When the Terminal Handler returns this message, it sets STATUS to to indicate 
normal completion of the write. STATUS is set to BADSCOMMAND (18) if the 
user specified a message type other thar WRITESTYPE or ALARMSTYPE (if 
other than WRITESTYPE, in the case of the minimal Terminal Handler). No data is 
transferred from the user buffer to the terminal. The write request must be re-issued 
to correct this non-fatal error. ACTUAL is undefined when an error message is 
returned. 

BUFFER ADDRESS must specify the F.AM address from which the Terminal 
Handler is to write out data. 

COUNT must specify the number of bytes: to be written out. It is the user's respon- 
sibility to ensure that COUNT does not exceed the length of the buffer. 

In ACTUAL, the Terminal Handler supplies the number of bytes written. If 
STATUS is zero, ACTUAL will always be equal to COUNT. 



Example. The following PL/M code illustrates the use of read and write request 
messages. This example is intended to be a succinct illustration of the essential use of 
the Terminal Handler for input and output; it is not a complete, executable user 
task. However, this code has been derived (with some simplifications) from the ex- 
ample real-time clock system that is presented and described in full in Appendix J. 
Appendix J should be helpful as an illustration of the use of the Terminal Handler in 
a complete, executable RMX/80 application system. 



/* MISCELLANEOUS "MACROS" */ 
DECLARE FOREVER LITERALLY 'WHILE 1 '; 
DECLARE WRITESTYPE LITERALLY '12'; 
DECLARE READSTYPE LITERALLY '8'; 
DECLARE CR LITERALLY 'ODH'; 
DECLARE LF LITERALLY 'OAH'; 



/* TERMINAL HANDLER REQUEST MESSAGES */ 
DECLARE (COMMAND, REPLY) STRUCTURE ( 



LINK 

LENGTH 

TYPE 

HOMESEXCHANGE 

RESPONSESEXCHANGE 

STATUS 

BUFFERSADR 

COUNT 

ACTUAL 



ADDRESS, 

ADDRESS, 

BrTE, 

ADDRESS, 

ADDRESS, 

ADDRESS, 

ADDRESS, 

ADDRESS, 

AiDDRESS); 



/* TEXT OF MESSAGES (BUFFERS) */ 
DECLARE SIGNONSMSGC) BYTE DATA( 

CR, LF, 'RTCLOK: VERSION 1 .0',CR,LF,LF, 
'ALL TIMES ARE 24-HOUR FORMAT: HH:MM:SS',CR,LF, 
09:22:30 = 9:22:30 AM'.CR.LF, 
17:30:00=5:30 PM'.CR.LF, 
00:00:00 = MIDNIGHT', CR.LF, 
24:00:00 = NO TIME - CLOCK IS OFF'.CR.LF); 
DECLARE COMMAND$MSG(81) BYTE; 
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/* TERMINAL HANDLER AND RESPONSE EXCHANGES */ 
DECLARE (RQOUTX.RQINPX) EXCHANGESDESCRIPTOR EXTERNAL; 
DECLARE (WRITEX.READEX) EXCHANGESDESCRIPTOR; 

CONSOL: PROCEDURE PUBLIC; 
DECLARE SCRATCH BYTE; 

/* INITIALIZATION SEGMENT */ 

CALL RQCXCH (.WRITEX); /* BUILD WRITE RESPONSE EXCH */ 

/* BUILD AND SEND SIGNON MESSAGE TO TERMINAL * / 

REPLY. LENGTH = SIZE (REPLY); 

REPLY.TYPE = WRITESTYPE; 

REPLY. RESPONSESEXCHANGE = WRITEX; 

REPLY. BUFFER$ADDR - .SIGNONSMSG; 

REPLY. COUNT = SIZE(SIGNON$MSG); 

CALL RQSEND (.RQOUTX,. REPLY); 

/* BUILD COMMAND MESSAGE */ 

CALL RQCXCH(.READEX); /* BUILD READ RESPONSE EXCH */ 

COMMAND. LENGTH = SIZE (COMMAND); 

COMMAND. TYPE = READSTYPE; 

COMMAND. RESPONSESEXCHANGE = .READEX; 

COMMAND.BUFFERSADR = .COMMANDSMSG; 

COMMAND.COUNT - SIZE(COMMANDSMSG); 

/* MAKE SURE SIGNON IS COMPLETE * / 

SCRATCH = RQWAIT(.WRITEX.O); 

/* END OF INITIALIZATION SEGMENT*/ 

/* LOOP TO ACCEPT COMMANDS FROM TERMINAL*/ 
DO FOREVER; 

CALL RQSEND(.RQINPX,. COMMAND); /* REQUEST INPUT/* 
SCRATCH = RQWAIT(.READEX.O); /* WAIT FOR T.H. TO FINISH */ 

/* USER CODE TO PROCESS THE DATA NOW 
IN COMMANDSMSG GOES HERE */ 

END;/* OF DO FOREVER*/ 
END CONSOL; 



Control Commands 

The full input-output Terminal Handler recognizes twelve one-character control 
commands; the minimal input-output Terminal Handler recognizes six of them. 
(No control commands are operative in the output-only versions.) The control com- 
mands fall into three general categories: line break control, line-edit control, and 
output control. The control commands have special meanings to the Terminal 
Handler, and are not echoed to the terminal. The Terminal Handler puts all other 
characters into its line buffer and echoes them back to the terminal. 

The full Terminal Handler uses a table (RQCTAB) to recognize control characters. 
When configuring the system, you can alter this table to use different key codes that 
may be generated more easily by some terminals. For instance, if your terminal sup- 
plies BREAK and cursor keys that require only one keystroke, you may use these 
keys instead of control characters that require two keystrokes. Since the Terminal 
Handler is ASCII-based, it does not use codes in the range 80H to OFFH, inclusive. 
Thus, if you wish to disable a particular control command, you need only assign the 
character a value greater than or equal to 80H. The control table is discussed further 
following the descriptions of the control commands. 
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In the minimal Terminal Handler, the values given in table 4-2 (for the commands 
recognized by the minimal Terminal Handler) are recognized; but these values can- 
not be altered, since no control table exists for the minimal Terminal Handler. 

To enter any of the control commands except CR, LF, ESC, or RUBOUT, strike the 
designated letter key while holding down the control key. 

NOTE 

Because different terminals have different features, the terminology used 
in the following descriptions may not apply directly to your terminal. For 
example, some terminals may have a DELETE or BACKSPACE key 
rather than a RUBOUT key. Refer to the manufacturer's literature for 
details concerning your terminal. 

Line Break Controls. 

CR (Carriage Return). The Carriage Return is a line break character, generated 
when the operator strikes the Carriage Return key. The character is placed in the line 
buffer and echoed to the terminal (its reprssentation in the display depends on your 
terminal). If there is room in the buffer, the Terminal Handler adds a Line Feed 
character to the buffer and echoes it to the terminal. 

LF (Line Feed). The Line Feed is a line break character in the full Terminal 
Handler; in the minimal Terminal Handler it is stored as a regular character and 
does not signify a line break. The characte- is placed in the line buffer and echoed to 
the display. 

ESC (ESCAPE). ESCAPE is a line break character. It is placed in the line buffer 
but is not echoed on the display. In the minimal Terminal Handler, ESC is not 
recognized as a line break control, but is treated as an ordinary character. 

Control-Z. The control-Z is an end-of-input character that can be used to simulate 
an end-of-file from the keyboard. Its exact meaning depends on your program logic. 
When a read request encounters a control-Z anywhere in the input line, the line buf- 
fer is cleared, and no data is moved into the user buffer. Instead, the Terminal 
Handler returns the read request message with its ACTUAL field set to zero. Your 
program can interpret this as an actual end-of-input and stop issuing read requests. 
Or, you can interpret this character as laving some other purpose within your 
system. Control-Z is not recognized by the minimal Terminal Handler. 



Line-Edit Controls. 

RUBOUT. RUBOUT deletes the last character from the line buffer and echoes the 
deleted character to the display. A BEL character is echoed if the operator attempts 
to RUBOUT past the beginning of the logical line. 

Control-R. Control-R issues a CR.LF sequence and then echoes a copy of all 
characters entered since the last break sequence. The control-R character itself has 
no echo. Control-R is useful in generating a clean copy of the current line, minus all 
characters you have deleted using RUBOUT. 

Control-X. Control-X deletes all charactjrs entered into the line buffer since the 
last break sequence; that is, it deletes the current input line. Control-X is useful for 
correcting errors that are inconvenient to correct using RUBOUT. Control-X echoes 
a pound-sign (#) after the characters to be deleted and then issues a Carriage Return 
and a Line Feed. 
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Control-P. Control-P causes the next character entered to be interpreted as data. 
This control is useful when you want to enter one of the control characters as a part 
of an input line. For example, you might want to enter a partially formatted line that 
is to be written out later with a Carriage Return and a Line Feed. A control-P must 
precede each of these control characters, or they will perform their normal func- 
tions. Control-P is not recognized by the minimal Terminal Handler. 



Output Controls. 

Control-S. Control-S suspends the display of output through the RQOUTX ex- 
change. It does not affect the RQALRM exchange; consequently, Debugger output 
continues if the Debugger is active. Tasks can continue producing output data while 
control-S is in effect, but the data cannot be displayed until a control-Q is issued. 
Control-S has no echo. It is not recognized by the minimal Terminal Handler. 

Control-Q. Control-Q resumes output through the RQOUTX exchange, thus 
negating the effect of the control-S. Control-S and control-Q are especially useful 
for suspending output during a debugging session. Notice that leaving a control-S in 
effect indefinitely may eventually delay execution of tasks that use RQOUTX for 
output when all their output buffers are filled. Control-Q has no echo. It is not 
recognized by the minimal Terminal Handler. 

Control-O. Control-O kills all output through the RQOUTX exchange. Control-O 
differs from control-S in that data that is normally written out through the 
RQOUTX exchange is simply ignored and therefore lost. Control-O remains in ef- 
fect until a subsequent control-O is encountered. Control-O has no echo on the full 
Terminal Handler; on the minimal Terminal Handler an echo of O is provided. 

Control-C. As mentioned previously, control-C is a special control used to invoke 
the Debugger. Its exact function is to send a message of type CNTRL$C$TYPE to 
the RQWAKE exchange; it also clears the Terminal Handler's type-ahead buffer. 



Control Table. 

The control table is a twelve-byte positional table, used by the full Terminal Handler 
to recognize control command characters. The full Terminal Handler provides a 
default control table with the values shown in table 4-1. 



Table 4-1. Full Terminal Handler Control Characters 



POSITION 


CHARACTER 


VALUE 





CR 


ODH 


1 


LF 


OAH 


2 


Control-S 


13H 


3 


Control-Q 


11H 


4 


Control-O 


OFH 


5 


Control-R 


12H 


6 


ESC 


1BH 


7 


RUBOUT 


7FH 


8 


Control-C 


03H 


9 


Control-X 


18H 


10 


Control-Z 


1AH 


11 


Control-P 


10H 
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You may specify a substitute value for any control command. You may also cancel 
the effect of a control by assigning it a value greater than or equal to 80H. 

If you need to change the control table, >ou can do so by means of the Interactive 
Configuration Utility. 



Operator Summary Sheet. When you design a system that includes the Terminal 
Handler, you must be certain that an operator is able to use your system. Perhaps 
the simplest way to do this is to provide a summary sheet for the operator. The 
following information can be used as a basis for such a summary sheet. (Note that 
some details will vary depending upon t ie individual characteristics of your ter- 
minal.) 

This sample operator summary sheet covers the capabilities of the full input-output 
Terminal Handler. If you are using the full output-only version or either of the two 
minimal Terminal Handlers, your summary sheet should not cover some of these 
features. 



System Start-Up 

1 . Turn ON the terminal . 

2. Make certain that the terminal is ON LINE, not local. 

3 . Turn ON the system . 

4. If necessary, strike the U (uppercase J) until the letters appears on the display. 



Editing Rules 

To End Input Line: Strike the Carriage Return, Line Feed, or the ESCAPE key. 

To Delete a Typo: Strike the RUBOUT key to delete the previous character. If you 
do this repeatedly, the display will begin to form a mirror image of the information 
already entered (CAT becomes C ATT AC). When you reach the letter to be cor- 
rected, simply retype the correct information. 

To Delete an Entire Line: Strike the Control and X keys together. The deleted line 
remains on your display, but is not entered into the system. A # character is placed at 
the end of the line to indicate that it has been deleted. You can then reenter the cor- 
rect data. 



Output Controls 

Sometimes you need to enter data at the sane time the system is writing data on your 
terminal. The following controls halt normal output. Alarms will still appear on 
your terminal. 



To Suspend Output: Strike the control and S keys together. If you leave the output 
suspended too long, system performance may be affected when too much data is 
waiting for output. 



To Resume Output: Strike the control and keys together. 
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To Kill Output: Strike the control and O (letter O) keys together. This control causes 
the loss of output data. To resume output, strike the control and O keys together 
again. This restarts the output, but all data that would have been written between 
the two commands is lost. 



End Of Input Control 

To End Input: Strike the control and Z keys together. This tells the system that you 
have finished entering data and no longer require the terminal. (Note to program- 
mer: This will only be true if your program interprets control-Z as end-of-input, as 
discussed previously under "Line-Break Controls.") 

Table 4-2 summarizes the features available in the various versions of the Terminal 
Handler. 

Table 4-2. Summary of Features for Configurations of the Terminal Handler 





Full Terminal Handler 


Minimal Terminal Handler 


Feature 










Input-Output 


Output-only 


Input-Output 


Output-only 


Exchanges: 










RQINPX 


YES 


NO 


YES 


NO 


RQOUTX 


YES 


YES 


YES 


YES 


RQWAKE 


YES 


NO 


YES 


NO 


RQALRM 


YES 


YES 


NO 


NO 


RQDBUG 


YES 


NO 


NO 


NO 


RQL6EX 


YES 


NO 


YES 


NO 


RQL7EX 


YES 


YES 


YES 


YES 


Control Commands: 










CR 


YES 


NO 


YES 


NO 


LF 


YES 


NO 


NO 


NO 


ESC 


YES 


NO 


NO 


NO 


Control-Z 


YES 


NO 


NO 


NO 


RUBOUT 


YES 


NO 


YES 


NO 


Control-R 


YES 


NO 


YES 


NO 


Control-X 


YES 


NO 


YES 


NO 


Control-P 


YES 


NO 


NO 


NO 


Control-S 


YES 


NO 


NO 


NO 


Control-Q 


YES 


NO 


NO 


NO 


Control-O 


YES 


NO 


YES 


NO 


Control-C 


YES 




YES 




Other: 










Control table (RQCTAB) 


YES 


NO 


NO 


NO 


Type-ahead buffer 


YES 


NO 


NO 


NO 


Baud rate search 


YES* 


NO 


NO 


NO 


*On iSBC 80/20 and 80/30 only 
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CHAPTER 5 
FREE SPACE MANAGER 



General Description 

Random-access memory (RAM) is one of the most valuable resources in a computer 
system. In many applications, however, RAM is used so ineffectively that it is 
almost wasted. Assume, for example, thai an initialization task executes only once 
and then is left unused until the next time the system is powered up. The RAM re- 
quired for the initialization task's messages is also unused most of the time. The Free 
Space Manager is provided to help you make the most efficient use of RAM in your 
system, by allowing you to reclaim RAM that is no longer needed by a task and 
make it available for use by other tasks. Thus the Free Space Manager allows you to 
treat RAM as a common resource to be shared dynamically by a number of tasks. 

Dynamic sharing of RAM via the Free Space Manager can substantially reduce the 
amount of RAM required in a system. As an example, assume that five tasks each 
require 2K of RAM, or a total of 10K. If these tagks are not normally in contention 
for system resources, it may be possible to reduce the RAM requirements for the 
tasks to 2K. Rather than permanently assign 2K blocks of RAM to each task, you 
can assign a single 2K block to the Free Space Manager. When a task needs to build 
a message or needs a buffer for some other purpose, the task requests the desired 
amount of RAM from the Free Space Manager. When the RAM is no longer need- 
ed, the task can surrender it back to the Free Space Manager so that it can be reused. 



The Free Space Manager is especially us;ful when a system deals with variable- 
length messages. Without the Free Space Manager, you must allocate enough RAM 
to accommodate the longest possible message. Many systems use maximum-length 
messages only infrequently; therefore, the system does not get the maximum possi- 
ble use from its RAM allocations. With ihe Free Space Manager, variable-length 
messages can be allocated from a common pool of RAM. When each message is 
assigned the amount of RAM required, any remaining RAM is available for other 
uses. 

For certain applications, in which there is little memory to manage, including the 
Free Space Manager is not justifiable in view of the memory it occupies. A rule of 
thumb is that the Free Space Manager is probably not warranted if there is less than 
2K bytes of memory to manage. 



Memory and Hardware Requirements 

The Free Space Manager requires less than 950 bytes of code space and approxi- 
mately 200 bytes of data space; it uses a 40-byte stack. Refer to Appendix D for exact 
byte counts. 

No special hardware requirements are imposed by the Free Space Manager. 

How the Free Space Manager Operates 

The Free Space Manager provides two basi: functions: 

• It maintains a pool of free RAM and, upon request from a task, allocates space 
from the pool. 

• It can accept blocks of RAM that are r o longer needed in the system and return 
them to the pool. 
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The Free Space Manager treats its blocks of RAM as messages; in fact, it uses certain 
message fields in the first eight bytes of the block, as described later in this section. 
However, you are free to use the RAM, including the message heading portion of the 
block, for any purpose once it has been allocated. 

Figure 5-1 illustrates the relationships between a user task and the Free Space 
Manager. (Though shown here as a single box, the Free Space Manager is actually a 
collection of tasks.) A user calls on the Free Space Manager by sending a message to 
one of two Free Space Manager exchanges. To request a RAM allocation, a task 
sends a message to the Free Space Manager's allocation exchange, RQFSAX. The 
Free Space Manager responds by returning the same message to a user-defined 
response exchange (RESP$EX). If the allocation has been made, the returned 
message contains the address of a block of RAM of the desired size. If the allocation 
has not been made, the message contains the length of the largest currently available 
block of RAM. 

To surrender a block of RAM, the task sends a message to the Free Space 
reclamation exchange, RQFSRX. The task surrendering RAM to the Free 
Manager does not receive a response message. 





FREE SPACE 




MANAGER 




Figure 5-1 . Free Space Manager Exchanges 



The size of an allocated block of RAM is controlled by two rules. First, the smallest 
block available is eight bytes. Second, blocks are always allocated in four-byte 
increments. Should a task request a block which does not satisfy both rules, the 
Free Space Manager will attempt to allocat e a slightly larger block that does conform 
to the rules. 



Using the Free Space Manager 



Initialization 

Before any allocation requests are made, a user task must initialize the Free Space 
Manager by telling it what areas of RAM are available for allocation. This is 
accomplished by sending one or more messages to the reclamation exchange of the 
Free Space Manager (RQFSRX). The Free Space Manager sends no response. 

Each message sent to the reclamation exchange represents a block of RAM to be 
made availabe for allocation. Each message must be physically located within the 
block that it represents. Before each message is sent to the Free Space Manager, 
your task must initialize the LENGTH field (bytes 2 and 3 of the block). The number 
stored in this field must be the number of bytes in the entire block. If this number is 
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not a multiple of four, the Free Space Manager will reduce the block size to the largest 
multiple of four. If the LENGTH field is set to less than four, the Free Space Manager 
will not reclaim the block. 

To reduce system overhead, do not send RAM that cannot possibly be allocated by 
the Free Space Manager. If, for example, the smallest allocation request in a system 
is for twenty bytes, you should not assign r on-contiguous blocks of less than twenty 
bytes to the Free Space Manager. To do so requires the Free Space Manager to keep 
track of this unused memory. This caution does not apply to contiguous blocks of 
memory. When the Free Space Manager encounters separate but contiguous blocks 
of free RAM, it merges the separate blocks together to form the largest possible 
single block. Therefore, if you initialize th : Free Space Manager by sending it three 
100-byte blocks of RAM and the blocks happen to be contiguous, the Free Space 
Manager treats the memory as a single 300- byte block. 

Allocation Request 

Allocation Request Message. A task requests a memory allocation by sending a 
message to the Free Space Manager's allocaton exchange, RQFSAX. The format for 
a memory allocation request message is she wn in figure 5-2. Asterisks denote fields 
that must be coded by the user task before the message is sent. Shaded fields are 
those that may be changed by the Free Space Manager when it returns the message. 



HOME EXCHANGE 



RESPONSE EXCHANGE" 



MSG LEfGTH- 
SED |~ 



Figure 5-2. Allocation Request Message 



Those fields that have specific meaning in the allocation request message are de- 
scribed in the following paragraphs. (For general information, refer to "Message 
Doding" in Chapter 2.) 

.ENGTH is 12. (Note that this is the length of the allocation request message, not the 
length of the desired memory allocation.) 



TYPE must be either FS$REQ$TYPE (4), for a conditional request, or 
UC$REQ$TYPE (5), for an unconditional request. These types are explained in the 
paragraphs that follow these message field definitions. 



HOME EXCHANGE is not used by the Free Space Manager. 



RESPONSE EXCHANGE must specify the address of the user-defined exchange 
where the requesting task waits for a response from the Free Space Manager. 

MSG LENGTH must specify the length of bytes of the block of RAM to be allocated. 
The value should be a multiple of four byte 3, and must be at least eight bytes. The 
Free Space Manager rounds up to the nearest multiple of four any request that is 
not a multiple of four. 

UNUSED is reserved for future use. It must be present even though it is not currently 
used. 

Conditional Request. When an allocation request of type FS$REQ$TYPE (4) is 
sent, the Free Space Manager responds by returning the user's request message with 
the TYPE field set to indicate either a positive or a negative acknowledgment. 
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The TYPE field remains unchanged when a positive acknowledgement is returned, 
and the MSG LENGTH field is set to the address of the allocated block of RAM. 

For a negative acknowledgment, the TYPE field is set to FS$NAK$TYPE (6), and 
the MSG LENGTH field indicates the size of the largest available block of con- 
tiguous RAM. The requesting task must test the TYPE field to determine whether 
the allocation was made, then take appropriate action. 

For a positive acknowledgement, the Free Space Manager also supplies information 
in certain fields of the allocated block of RAM, as described later under "Format of 
Allocated Message." 

If the acknowledgment is negative, no RAM is allocated. The requesting task can 
check the MSG LENGTH field to determine the size of the largest available RAM 
block; if the task can use a block of that size, it can issue a second request message. 
Note, however, that the amount of available RAM is subject to change if some other 
task requests or surrenders RAM before the second request is honored. 

In making conditional requests, care must be taken to avoid a "lockout" situation. 
If a task loops continuously, making a conditional allocation request on each itera- 
tion until it gets a positive acknowledgment, but never waiting at an exchange, and if 
this task has a relatively high priority, it will "lock out" the Free Space Manager 
reclamation and merge tasks, so that no memory will ever be freed to satisfy the re- 
questing task. This situation can occur with a Disk File System READ or DISKIO 
request if dynamic buffer allocation is selected (see Chapter 7, "Buffers"), since 
DFS makes a conditional allocation request to the Free Space Manager. The situa- 
tion can be avoided by having the requesting user task perform a timed RQWAIT 
operation (at an exchange where no messages are sent) each time around the loop, 
giving other tasks the opportunity to run. 

Unconditional Request. You can avoid the logic needed for testing the response 
type by issuing an allocation request of type UCSREQSTYPE (5). This type of 
message never produces a negative acknowledgment. When an unconditional re- 
quest is issued, the Free Space Manager responds with a positive acknowledgment 
(as described under "Conditional Request") if the request can be filled. However, if 
the request cannot be filled, the requesting task waits indefinitely until sufficient 
memory becomes available. At that time, a positive acknowledgment is returned. 

When the RQWAIT operation is used to wait for a response to an unconditional re- 
quest, the RQWAIT should not normally specify a time limit. To do so may allow 
your task to time out and resume execution before its allocation request has been 
honored. However, the unconditional request remains in effect and will eventually 
be filled. Since the task is no longer waiting for a response, it may be unaware that 
the request has been filled. This situation creates many possibilities for problems 
and should be avoided. 

Format of Allocated Message. Whenever the Free Space Manager is able to grant 
a request for a block of RAM, two messages are generated. The first message, called 
the allocated message, is built within the block of allocated RAM. Its fields (illus- 
trated in figure 5-3) are described in the following paragraphs. The second message 
generated is a modification of the request message that was sent to the Free Space 
Manager. It differs from the request messa ge only in one regard— the MSG LENGTH 



o 

2 
4 
5 
7 
9 



LENGTH 

TYPE J 

HOME EXCHANGE 
RESPONSE EXCHANGE 
REMAINDER 



Figure 5-3. Allocated Message 
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field of the message now contains the address of the allocated block of RAM. It is 
this second message that is sent to the response exchange field designated in the 
request message. 

Those fields that have specific meaning in the allocated message are described in the 
following paragraphs. (For general infoimation, refer to "Message Coding" in 
Chapter 2.) 

LENGTH is set equal to MSG LENGTH from the allocation request message 
(rounded up to a multiple of four). This indicates the total length of the allocated 
message (block). 

TYPE is not used by the Free Space Manager. 

HOME EXCHANGE is set to the address of the Free Space Manager's reclamation 
exchange, RQFSRX. 

RESPONSE EXCHANGE is not used by the Free Space Manager. (In an eight-byte 
allocation, only one byte of this field is present.) 

The REMAINDER is an undefined user area. 

The address returned in the MSG LENGTH field of the response message provides 
access to the allocated RAM. PL/M programmers can use this as a base address. 
Assembly language programmers can load this address into the H and L registers 
and use it as a base for addressing the allocated RAM. 

Although the RAM is allocated as a message, you need not use it as such. You 
might, for example, use the RAM as a scratchpad for a calculation. However, if you 
write over the LENGTH field of the message heading, you must restore the 
LENGTH before sending the RAM back to the Free Space Manager for reclama- 
tion. 

Timing Considerations. When a task requests a RAM allocation, the requesting 
task typically waits while the Free Space Manager attempts to allocate the desired 
amount of contiguous memory. However, when the task waits, all ready tasks with 
priorities higher than the Free Space Manager execute before the Free Space 
Manager. Although the allocation routine itself is highly efficient, the possible ex- 
istence of higher-priority ready tasks makes it difficult to predict the elapsed time 
between a RAM request and the actual allocation. There are two potential solutions 
to this problem: 

• The priority of the Free Space Manager is user-assigned when the system is 
configured. This allows you to assign ihe same priority to both the Free Space 
Manager and a task with a critical timing requirement. This will insure that only 
tasks with priorities higher than that of the requesting task will preempt the Free 
Space Manager. 

• The task can request the RAM allocation before it reaches the code with critical 
timing requirements. 

Remember that the Free Space Manager t eats RAM as a shared resource. When 
many tasks contend for this resource, the Free Space Manager may temporarily be 
unable to fulfill a request. This may cause i task making an unconditional request 
to wait until enough RAM is returned to the pool to fill the request. 

Allocation Technique. The Free Space Manager maintains a list of available blocks 
of RAM. This list indicates the starting address and length of each block. However, 
to make allocations as quickly as possible, the Free Space Manager allocates 
memory on a "first-fit" rather than a "best-fit" basis. For example, assume that 
blocks of 40, 28, and 100 bytes are available when a request for a 28-byte block is 
honored. The 28-byte allocation is made from the 40-byte block, thus leaving a 12- 
byte fragment. This 12-byte fragment may or may not be used if there is a . subse- 
quent request for an eight- or twelve-byte allocation. 
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Reclamation 

Sending a Message for Reclamation. A task returns a block of RAM to the Free 
Space Manager by sending it in the form of a message to the Free Space Manager's 

reclamation exchange, RQFSRX. If the LENGTH field (the third and fourth bytes) 
of the block has been changed since the block was allocated, or if the length of the 
block being returned is different, you must set this field. The length must be that of 
the memory block being returned, and should be a multiple of four bytes. The Free 
Space Manager rounds down any LENGTH fields that are not multiples of four. 
This is the only field in the message that need be set before it is sent. 

When a user task receives an allocation of memory from the Free Space Manager, 
the task should save the address of the allocated message (from the MSG LENGTH 
field of the response message). When the allocated message is no longer needed, the 
task need only set the LENGTH field of the message (if it has been changed), then 
call RQSEND with the address of RQFSRX and the message address as parameters. 

Reclamation Technique. When a block of RAM is surrendered, the Free Space 
Manager checks to see if it is adjacent to any other block of available RAM. If so, 
the Free Space Manager merges the blocks into a single, larger block. The task that 
performs these merges runs at priority level 254. The task only uses processor time 
that would otherwise be spent in a HALT state. 

Note that when many tasks are making heavy use of system resources, the merge 
task may not be able to run often enough to satisfy the needs of the system. To 
alleviate this problem you can: a) avoid returning memory to the Free Space 
Manager when a task needs to use it again in a relatively short time, thus lightening 
the load on the Free Space Manager; or b) provide the Free Space Manager with 
more memory, so that spare memory will almost always be available. 

NOTE 

When the Free Space Manager accepts a block of memory from one of 
your tasks, it does not check for overlap. If your task frees a block of RAM 
and claims that it is longer than it actually is, the Free Space Manager 
will accept the incorrect size. Errors of this nature can result in a single 
block of RAM being allocated to two different tasks simultaneously. 

Coding Examples 

The basic steps for requesting a memory allocation are: 

• Build a request message 

• Send (RQSEND) the message to the Free Space Manager 

• Wait (RQWAIT) for a response from the Free Space Manager 

• If the request was conditional, check TYPE field of response message to ensure 
that the allocation was successful. 

The basic steps in returning memory to the Free Space Manager are: 

• Set the LENGTH field (third and fourth bytes) of the block of memory being 
returned 

• Send (RQSEND) the memory as a message to the Free Space Manager. 

PL/M. In the following PL/M code, assume that EXTERNAL declarations have 
been provided for the Free Space Manager exchanges RQFSAX and RQFSRX, that 
the exchange REQEX has been created and declared for use in communication with 
the Free Space Manager, and that the address variable ALLOC$MSG$ADDR has 
been declared. Also assume that the Free Space Manager has been initialized by 
sending one or more blocks of memory, in the form of messages, to RQFSRX. 
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The following code builds a memory allocation request message: 

I* DECLARE ALLOCATION REQUEST MESSAGE */ 
DECLARE REQMES 

LINK 

LENGTH 

TYPE 

HOMESEXCHANGE 
RESPONSESEXCHANGE 
MSGSLENGTH 

/* BUILD ALLOCATION REQUEST MESSAGE */ 

REQMES. LENGTH = 11; 
REQMES. TYPE = FS$REQ$TYPE; 
REQMES. RESPONSESEXCHANGE = .REQEX; 
REQMES.MSGSLENGTH = 40H; 

After the message is built, the user task sends it to the allocation exchange and waits 
for a response: 

CALL RQSEND(.RQFSAX,. REQMES); 
SCRATCH = RQWAIT(. REQEX.O); 

The task checks the TYPE code returned by the Free Space Manager to see if the re- 
quest was honored. If not (TYPE=FS$NAK$TYPE), the task requests allocation 
repeatedly until the allocation is obtained Note that in all requests for allocation 
after the first, the task voluntarily surrenders the processor by waiting for one 
system time unit. (This example assumes that no message will arrive at the REQEX 
exchange during the wait.) This gives other application tasks and the Free Space 
Manager reclamation and merge tasks a chance to run and to enlarge the RAM pool. 
Other tasks contending for the system, however, could still prevent the reclamation 
and merge tasks from gaining control: 

DO WHILE REQMES. TYPE = FS$NAK$TYPE; 

SCRATCH = RQWAIT(. REQEX, 1); 

REQMES. TYPE = FS$REQ$TYPE; /'RESETTYPE*/ 

REQMES. MSGSLENGTH = 40H; '/RESET LENGTH*/ 

CALL RQSEND(.RQFSAX,. REQMES); 

SCRATCH = RQWAIT(.REQEX.O); 

END; 

/ *SAVE ADDRESS OF ALLOCATED BLOCK* / 
ALLOC$MSG$ADDR = REQMES. MSGSLENGTH; 

This example does not try to use a smaller allocation when it receives a negative 
acknowledgment (MSGSLENGTH contains the size of the largest block currently 
available). Nor does it make use of the time available to it to perform other process- 
ing between successive requests for allocation. Therefore it would be more ap- 
propriate for the task to make an unconditic nal request and to wait indefinitely until 
the allocation can be made: 

/*BUILD UNCONDITIONAL REQUEST MESSAGE*/ 

REQMES. LENGTH = 11; 
REQMES. TYPE = UCSREQSTYPE; 
REQMES. RESPONSESEXCHANGE = .REQEX; 
REQMES. MSGSLENGTH = 40H; 



STRUCTURE ( 

ADDRESS, 

ADDRESS, 

BYTE, 

ADDRESS, 

ADDRESS, 

ADDRESS); 
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/'REQUEST ALLOCATION & WAIT UNTIL OBTAINED*/ 

CALL RQSEND(. RQFSAX, .REQMES); 
SCRATCH = RQWAIT(. REQEX, 0); 

/•SAVE ADDRESS OF ALLOCATED BLOCK* / 

ALLOC$MSG$ADDR = REQMES.MSG$LENGTH; 

Assuming that the LENGTH field of the allocated block has not been altered, the 
block can be returned to the RAM pool by sending it to the reclamation exchange: 

CALL RQSEND(.RQFSRX,ALLOC$MSG$ADDR); 



Assembly Language. The following assembly language code performs the same 
functions as the PL/M code given in the preceding section. Assume that RQFSAX 
and RQFSRX have been declared external, that the user exchange REQEX has been 
created and declared, and that REQMES has been declared in dedicated RAM. 

AGAIN: LXI H.11H ;LOAD H&L WITH MESSAGE LENGTH (11) 



SHLD 

MVI 

STA 

LXI 

SHLD 

LXI 

SHLD 



REQMES+2 
A,4H 



REQMES+9 



REQMES+4 
H, REQEX 
REQMES+7 
H.40H 



;SET MESSAGE LENGTH 

;LOAD ACC WITH MESSAGE TYPE (4) 

;SET MESSAGE TYPE 

;LOAD H&L WITH ADDRESS OF RESPONSE EXCHANGE 
;SET RESPONSE EXCHANGE ADDRESS 
;LOAD H&L WITH MSG LENGTH (40H) 
;SET MSG LENGTH TO 40H 



Before calling the RQSEND operation, the program must load the exchange address 
and message address into BC and DE register pairs, respectively: 



LXI B, RQFSAX ;LOAD B WITH ALLOC EXCHANGE ADDRESS 
LXI D, REQMES ;LOAD D WITH REQUEST MESSAGE ADDRESS 
CALL RQSEND 



The task now waits at the REQEX exchange until the Free Space Manager responds. 
First, however, the B and D registers must be loaded with the address of the REQEX 
exchange and the RQWAIT time limit: 



LXI B, REQEX 
LXI D,0H 
CALL RQWAIT 



;LOAD B WITH RESPONSE EXCHANGE 
;NO SPECIFIC TIME LIMIT FOR THIS WAIT 




The TYPE code returned by the Free Space Manager is tested and the request is re- 
issued until it is satisfied. The task waits for one system time unit between requests: 



LXI H, REQMES+4 ; H&L TO POINT TO TYPE FIELD 

MVI A,4H ;POSITIVEACK IN ACCUMULATOR 

CMP M ;POSITIVEACKINTYPE? 

JZ GOTIT ;YES, CONTINUE 

LXI B, REQEX ;NO, SURRENDER FOR 1 STU 

LXI D,1H 

CALL RQWAIT 

JMP AGAIN ;TRY AGAIN 



GOTIT: EQU O 



LHLD H, REQMES + 9 ;GET ADDRESS OF BLOCK 
PUSH H ;SAVE ON STACK 
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At this point the program has copies of the message address in the H and L registers 
and on the stack. The program can gain access to any location in the message by in- 
crementing the message address in the H and L registers. 

As soon as the message is no longer required, it is returned to the Free Space 
Manager. 



LXI B.RQFSRX 
POP D 
CALL RQSEND 



LOAD RECLAMATION EXCHANGE ADDRESS 

LOAD D WITH MESSAGE ADDRESS 

SEND MESSAGE TO FREE SPACE MANAGER 
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General Description 

RMX/80 provides a Debugger especially designed for use in the RMX/80 real-time 
environment. Because the real-time environment presents certain unique debugging 
situations, this Debugger is provided in addition to other Intel diagnostic tools such 
as the ICE-80 or ICE-85 In-Circuit Emulator. The Debugger can be used in conjunc- 
tion with ICE-80 or ICE-85 to obtain some capabilities (such as memory mapping 
and debugging an inoperative system) not available in the Debugger alone. 

The Debugger allows you to communicate with your RMX/80 system through the 
Terminal Handler. The Debugger offers services beyond those provided by ICE-80 
and ICE-85. For example, the Debugger can format and display RMX/80 structures 
such as Task Descriptors and Exchange Descriptors. Tracing the dynamic changes in 
these structures can give you a good understanding of what is happening in the 
system. Used in this fashion, the Debugger can be a powerful educational tool, and 
can also help improve the performance of systems that are executing correctly. 

A basic understanding of RMX/80 system operation will aid you considerably in 
debugging your system. The "Details of System Operation" section of Chapter 2 
supplies helpful information on this subject. In using the Debugger, you will prob- 
ably want to refer often to this section, particularly the system control structures 
diagram at the end of the chapter (figure 2 8). 




Debugger Capabilities 

The RMX/80 Debugger is provided in two versions, an active Debugger and a 
passive Debugger. The active Debugger allows you to look into the system and to 
modify it. The passive Debugger allows you to look into the system, but does not 
allow you to modify it. 

Because it offers a greater number of features, the active Debugger is the logical 
choice for debugging a prototype system with sufficient memory or when you are us- 
ng ICE-80 or ICE-85 with an Intellec Development System. Because it requires less 
memory, the passive Debugger may be the only choice when memory is limited and 
when ICE-80 or ICE-85 is not available. 

The passive Debugger allows you to: 

• Examine the contents of specified locations in memory. 

" View the contents of system lists, including the Task List, Exchange List, Ready 
List, Suspend List, Delay List, and the list of all tasks or messages waiting at 
any specified exchange. 

" Look at formatted system control structures, including Task Descriptors, 
Exchange Descriptors, and messages. 

• Quit the debugging session. 

The active Debugger includes all the featu-es of the passive Debugger, and also 
allows you to: 

« Modify the contents of specified memory locations and of fields in system lists, 
Task Descriptors, Exchange Descriptors, and messages. 

• Define symbolic names for numeric values such as addresses (and change or 
remove the names if necessary). 
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• Execute an RMX/80 or user-supplied procedure. 

• Set breakpoints at memory locations (execution breakpoints) or on exchanges 
(sends or waits). 

• Display and/or modify the registers of a task that has incurred a breakpoint. 

• Set up a periodic scan of task stacks for overflow conditions. 

One special feature of the RMX/80 Debugger is that the system does not stop when 
a breakpoint occurs; the task incurring the breakpoint is (optionally) suspended, but 
the rest of the system continues to run. This feature is especially important in the 
real-time environment, when it is crucial that certain processes not be interrupted. 



Use Environment 

The Debugger differs from other RMX/80 extensions in that it is more likely to be 
used for testing in a prototype system than in a final application system. There is 
relatively little need for the Debugger in an already thoroughly debugged system. 
However, some users may elect to include the Debugger in systems that may require 
field troubleshooting. 

The Debugger requires the services of the full input/output Terminal Handler, 
which includes a number of exchanges and controls that support the Debugger. (The 
system being debugged must include a terminal.) 

The Debugger is designed for use with the iSBC 80/20, 80/24, 80/30, 80/ 10A and 
80/10B Single Board Computers. Because of differences in interrupt handling, there 
is one version of the Debugger of the iSBC 80/20, 80/24, and 80/30, and another 
version for the iSBC 80/ 10's. 



Memory and '. 

The active Debugger requires less than 1 IK (K=1024) bytes of code space and less 
than 1700 bytes of data space. The passive Debugger requires less than 4K bytes of 
code space and less than 600 bytes of data space. Both active and passive Debuggers 
use a 64-byte stack. Refer to Appendix D for exact byte counts. 



No special hardware requirements are imposed by the Debugger in a fully operating 
system, other than the Terminal Handler requirements (see Chapter 4). However, 
refer to the following section, "Using the Debugger," for the minimal hardware 
configuration necessary to run the Debugger during system development. 



How the Debugger Operates 



The Debugger operates in close conjunction with the Terminal Handler. The sec- 
tions in Chapter 4 entitled "Terminal Handler Exchanges" and "Debugger Ex- 
changes" describe the relationships between the Terminal Handler, the Debugger, 
user tasks, and exchanges. These relationships are summarized in figure 6-1 . 
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Figure 6-1 . Terminal Handle: -Debugger Relationships 



Using the Debugger 

Before using the Debugger in a developing system, you must decide how you wish to 
map Debugger code into your prototype memory, and must also establish an opera- 
tional hardware configuration. These considerations are discussed in this section. 

Once the hardware and software are configured for your prototype system (refer to 
Chapter 3 for software configuration), you communicate with the Debugger by a set 
of commands entered from the terminal. (The Terminal Handler must be included in 
your prototype system.) Following the discussions of memory mapping and hard- 
ware configuration, this chapter provides a complete description of all Debugger 
commands, a list of error messages, and some general debugging suggestions. 



Memory Mapping of Debugger Code 

For most RMX/80 applications, the final goal is to have the code be ROM-resident. 
The Debugger, however, is primarily useful during system development, and may 
not be included at all in the finat ROM-resident application system. Thus it is useful 
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here to mention the different memory mapping options that may be chosen. Debug- 
ger code may be mapped into a system in several ways: 

• Debugger code may be placed in your system's PROM. 

• Debugger code may be placed in your system's RAM via ICE-80 or ICE-85 . 

• Debugger code may be loaded into Intellec Microcomputer Development 
System memory by using the ICE-80 or ICE-85 In-Circuit Emulator. 

The first two options require your system to include enough memory to ac- 
commodate the Debugger. Typically, th s implies the use of a memory expansion 
board. 

Because of the cost of programmable ROM's, Debugger code is normally placed in 
ROM only when it is to be part of the application system. This option is useful for 
field-testing systems. 

Prototype systems with sufficient RAM sometimes locate Debugger code in RAM. 
Application systems typically avoid loading code into RAM, since this requires the 
use of a peripheral device for program loading. 

The third option — using ICE-80 to map the Debugger into the Intellec Development 
System's memory — is the most practical for typical systems. Notice, for example, 
that the Debugger must run under the RMX/80 Nucleus and requires the use of the 
Terminal Handler. Therefore, when RMX/80 is not operative, neither is the De- 
bugger. The ICE-80 and ICE-85 diagnostics may be helpful in this situation. 



Hardware Configuration 

Before attempting to use the Debugger, you must be certain that your hardware con- 
figuration is fully operational. The most efficient way to do this is to load and 
operate the Demonstration System with ICE-80 (for iSBC 80/20 and 80/10 systems) 
or ICE-85 (for iSBC 80/24 and 80/30 systems). For installation of ICE-80 or ICE-85 
in the RMX/80 environment, refer to Appendix F. 

The Demonstration System, described in Appendix I, exercises the Nucleus, Ter- 
minal Handler, Free Space Manager, and Debugger, plus a simple command line in- 
terpreter. By using the Demonstration System, you can be certain that both your 
hardware configuration and the RMX/80 software are operating properly. 

Certain hardware modifications, described in Appendix F, must be made in order to 
operate RMX/80 software on your iSBC system. Also, you must be certain that the 
jumper-wired addresses of your iSBC memory are appropriate for your system. 
Again, the easiest way to check this is by implementing the Demonstration System. 



Configuring your system hardware is basically a one-time learning process. 
After you learn the steps needed to bring up your prototype system, you can 
apply the same steps to application sy stems without repeating the testing 
described here. 



Debugger Commands 



Entering Commands. You communicate with the Debugger by means of the 
Debugger commands. All Debugger commcinds must be entered through a terminal 
running under the RMX/80 Terminal Handler. 
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You invoke the Debugger by entering a control-C at the terminal. This awakens the 
Debugger and directs subsequent terminal entries to the Debugger rather than to 
your system. (Control-C also clears the Terminal Handler's type-ahead buffer.) The 
Debugger remains in effect until you enter the letter Q followed by a carriage return 
at the terminal. This signifies the QUIT command, which deactivates the Debugger. 
Subsequent terminal entries are directed to your system rather than to the Debugger. 
The Debugger remains inactive until another control-C is entered. 

Throughout this chapter, the term debugging "session" refers to the period that 
starts when you invoke the Debugger wi .h a control-C and ends when you return 
control to the Terminal Handler via the QUIT command. It is assumed that the 
system continues to run and is not restarted. 

While the Debugger is active, the Terminal Handler is also still active; all Terminal 
Handler control commands are operative;. You may, for instance, correct an im- 
properly entered Debugger command with a series of RUBOUTs, then generate a 
fresh copy of the line using control-R. During a debugging session, you may wish to 
suspend terminal output by giving the control-S command, or to kill the output with 
control-O. If you do so, you should remember to reverse the command with 
control-Q or another control-O when you quit the debugging session. 

The Debugger indicates that it is ready for a command by displaying an asterisk (*) 
as a prompt character. You enter a Debugger command by typing its op-code on 
your terminal. Many op-codes may be followed by optional characters to specify 
particular functions. You terminate the command by striking the Carriage Return 
key. Certain commands allow you to enter a large number of options in a single en- 
try rather than enter the command repeatedly. 

The first four commands shown in table 6-1 (MEMORY, VIEW, FORMAT, and 
QUIT) are common to both the active and the passive Debugger. However, the ac- 
tive Debugger provides more options for certain commands than the passive Debug- 
ger. (Refer to the detailed command descriptions later in this section.) The rest of 
the commands are available only in the active Debugger. 

Table 6- 1 . Debt gger Commands 



COMMAND 




OP-CODE 


FUNCTION 


MEMORY 




M 


The MEMORY command produces a hexadecimal display of the value at the 
current memory address. Options allow you to specify a one-byte or two- 
byte word display; to alter the current address; and to modify the value at 
the current address. 


VIEW 




V 


The VIEW command displays the contents of a particular RMX/80 system 
list. For example, V R displays the current contents of the Ready List. A 
number of options allow you to specify the list to be displayed. 


FORMAT 




F 


The FORMAT command formats and displays the contents of a Task 
Descriptor, Exchange Descriptor, or message. 


QUIT 




Q 


The QUIT command terminates the debugging session. The Debugger 
surrenders control and waits for you to enter another Control-C. All subse- 
quent terminal input is directed to your system rather than to the Debugger. 


EXECUTE* 




X 


The EXECUTE command allows you to enter the address of a PL/M 
procedure or assembly language subroutine to be executed along with any 
parameters required by the procedure. For example, you might activate a 
task by executing an ROSEND operation that sends a message to the ex- 
change where the task is waiting. 


•Available only 


n the active Debugger. 




Table 6-1 . Debugger Commands (Cont'd.) 



COMMAND 


OP-CODE 


FUNCTION 


DEFINE* 


D 


The DEFINE command allows you to assign PL/M-like symbols (numeric 
variables) to frequently-used memory addresses or other numeric values. 


REMOVE* 


Z 


The REMOVE command allows you to remove a previously-defined numeric 
variable from the system. 


CHANGE* 




No op-code is specified for the CHANGE command. Instead, you name the 
item to be changed, Followed by an equals sign and the new value. The 
CHANGE command allows you to establish or change a breakpoint, define a 
Breakpoint Task, alter the Breakpoint Task's registers, or change the value 
of a numeric variable previously entered via a DEFINE command. 


DISPLAY* 




No op-code is specified for the DISPLAY command. Instead, you name the 
item to be displayed. The DISPLAY command displays numeric variables, 
breakpoint registers, and various items associated with the currently defin- 
ed Breakpoint Task. If, for example, R is specified, the contents of the 
task's registers are displayed (accumulator, flags, etc.). 


GO* 


G 


The GO command resumes the Breakpoint Task— i.e., makes it ready to run 
again. When the task resumes running, execution continues with the next 
instruction to be executed when the break occurred. 


SCAN* 


S 


The SCAN command periodically checks the Task Descriptors of all tasks in 
the system to determine whether any task's stack has an overflow condi- 
tion. If so, the SCAN command issues an overflow message that identifies 
the task with the overflow condition. 



•Available only in the active Debugger. 



Using the Detailed Command Descriptions. The first four commands 
described — MEMORY (M), VIEW (V), FORMAT (F), and QUIT (Q) - are com- 
mon to both the active and the passive Debugger. However, the active Debugger 
allows certain options not supported by the passive Debugger. In the descriptions of 
these first four commands, options available only for the active Debugger are 
shaded. Users of the passive Debugger cannot use the shaded options. The next 
seven commands— beginning with the EXECUTE command— apply only to the 
active Debugger. 

In the format definitions, braces enclose the different options (arranged in a vertical 
column) available for a command. Square brackets enclose optional fields in a com- 
mand entry. An ellipsis (. . .) indicates that allowable options may be repeated any 
number of times. The term "expression" denotes a hexadecimal constant, a numeric 
variable, or a series of these added or subtracted. (Examples: 21 A2, .B, .C + Al .) 

Tokens (individual items or options within an entry) may be either run together or 
separated by blanks, provided that alphanumeric characters belonging to con- 
secutive tokens are always separated by at least one blank. This restriction does not 
apply to punctuation (non-alphanumeric) characters. For instance, a MEMORY 
command specified as M=!W321 A is not permitted, but M=!W 321A is valid. 

Numeric parameters must be entered in hexadecimal. (No "H" suffix is required.) 
Likewise, the Debugger gives responses in hexadecimal. 
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MEMORY Command. 

Function. The MEMORY command produces a hexadecimal display of the con- 
tents of the current memory location. Options allow you to specify a one-byte (byte) 
or two-byte (word) display; to alter the current address; and to modify the value at 



Format. 




mm 



Mi \ 

/ 

no ertry 
=exp'ession 
=M expression 
=M expression:expression 

Description. The shaded options are ava lable only in the active Debugger. The 
ellipsis indicates that allowable options ma y be repeated any number of times (up to 
a full input line). Different options may also be combined in an input line. 

When the Debugger receives a MEMORY command with a string of options, it 
responds to the options one at a time, from left to right. If there are syntax, seman- 
tic, or processing errors, only the leftmost error is reported, and none of the subse- 
quent commands are processed. For this reason, it is generally best to keep your 
string of options relatively short. 

Although the MEMORY command offers z number of options, they break down in- 
to three rather simple categories as shown b:low; 



size control 



address control 



alter memory 



!I3 
!W 

expression 

tg 
<§ 
\ 

/ 

no entry 

= expression 
= vt expression 
= vl expression:expression 



The size control options allow you to specify whether a single byte or a two-byte 
word is to be displayed and/or updated. The !B option requests a byte display; !W 
requests a two-byte word display. The Debugger initially defaults to a byte display 
if neither option is specified, and thereafter defaults to the last option specified. 
Displays always have a hexadecimal format. Thus, the ASCII character A is 
displayed as 41; the ASCII character 4 is displayed as 34. 



Word mode is particularly useful in helping you to read address-type variables or in- 
structions in memory. Since the 8080 or 8085 processor considers the low-order byte 
of an address variable to be the byte with the lower memory address, a byte display 
shows the two bytes reversed from the order in which they should be read. Word 
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mode displays pairs of addresses as si<teen-bit hexadecimal numbers. (Bytes are 
paired off starting with the specified memory location, whether the address is even 
or odd.) 

The address control options allow you to specify the address portion of the M com- 
mand. This address, which determines the location to be displayed, may range from 
through OFFFF (hexadecimal). You must be certain the current address is valid 
within your system. Note, for example, i;hat few application systems contain 64K of 
memory; you must not attempt to display non-existent memory. 

The address control options both alter the current address and display the resulting 
address and its contents. The options have the following meanings: 

• Expression — An expression is usually given as a hexadecimal address. Thus, the 
command M 4000 sets the current address to 4000H and displays the value at 
that address. The expression may ulso include a value to be added to or sub- 
tracted from the base address. Assume, for example, that from looking at a 
Task Descriptor, you know that a stock is based at address 40A6 and has a size 
of 64 bytes (40H). The command M!B 40A6+3F displays the contents of the 
last byte of the stack. 

Users of the active Debugger have the option of assigning addresses to PL/M- 
Hke symbolic addresses. Thus, if the address 4000 is assigned to the symbolic ad- 
dress .A, the command M.A displays the contents of address 4000. 

• Expressionrexpression— This option allows you to specify a range of addresses 
to be displayed. Thus, the command M 4001:4005 displays the five bytes begin- 
ning at address 4001 and continuin ? through address 4005. By contrast, the 
command M!W 4001:4005 displays sue bytes located at 4001 through 4006 as 
three four-digit hexadecimal values. Notice that you must be certain that the 
ending address is greater than the starting address; otherwise, only one item will 
be displayed. 

• @ — the @ option makes the contents of the currently displayed location the 
current address. Thus, if you happen to be looking at the MESSAGE field of a 
Task Descriptor, the M @ command sets the current address to the address of 
the message and displays the LINK field of that message. When using the @ op- 
tion, you must be certain that the new current address is a defined location. 

• \ — The \ option decrements the cuirent address by one for byte mode (!B 
specified) or by two for word mode (!W specified). Thus, if the current address 
is 4005, the command M \\\\\ displays the contents of locations 4004, 4003, 
4002, 4001, and 4000 in byte mode, or t;he contents of locations 4003, 4001, 3FFF, 
3FFD, and 3FFB in word mode. 

• / — The / option increments the current address by one for byte mode (!B 
specified) or by two for word mode (!W specified). Thus, if the current address 
is 4000, the command M ///// displays the contents of locations 4001, 4002, 4003, 
4004, and 4005 in byte mode, or the contents of locations 4002, 4004, 4006, 4008, 
and 400A in word mode. 

• no entry — Coding an M command with no options is the same as coding the M 
command with a single / option. Thus, the commands M and M / are 
equivalent. If the current address is 4000, both commands display the contents 
of location 4001 in byte mode, or the contents of location 4002 in word mode. 

The alter-memory options are available only with the active Debugger. These op- 
tions alter and then display the contents of the specified memory locations to verify 
the change. The alter-memory options rely on previous options for certain 
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words or bytes and whether a single address or a range of locations is to be modifi> 

The options have the following meanings: 

• "expression— Fhis option sets the contents of the current byte Or word equal to 
the value of the expression. If the previous option specified a range of ad- 
dresses, this option alters the entire sequence of locations. For example, assume 
that a previous M command specific .1 the range of locations 4000:4005. The 

— < ■ , : \ : ; 

• =M expression— With this option, "expression" must evaluate toanaddress in 
memory. 1 lie \ aluc at that address is lien used to alter the current byte or word. 
If the previous option specified a range of addresses, this option alters the entire 
sequence of locations. 

For example, assume that a previous M command specified the range of loca- 
tions 4000:4005 and that location 300} contains the ASCII character A <41H). 
The command M=M 3000 moves the litter A (41H) into locations 4001 through 
4005. 

• =M expressiomexpression— -This option moves the sequence of characters 

. ' vo ;.u> • ■ ' ■ ■ • . :;c c . 

with the current address. Assume, for example, that locations 3000 through 
3005 contain the letters ABCDEF, and the current address is 4000. The com- 
mand M«M 3000:3005 moves the characters ABCDBF to locations 4000 
through 4005. 

ff the previous M option specifies a range of addresses, that previous option 
controls the size of the destination field; the source data is truncated or repeated 
as required. In the above example, if the previous M command specified the ad- 
dresses 4000 through 4<XJ2, the command M=M 3000:3005 moves only the let- 
ters ABC. If the previous command sfeeified addresses 4000 through 4009, the 
command M=M 3000:3005 moves the letters ABCDEFABCD. 

NO"E 

It is possible to request quite a lengthy display with ihe 
mand (M 3000:4000, for exampe). You can terminate such a 
display by entering a control-C. This terminates i 

end of the current output line. 

VIEW Command. 

Function. The VIEW command displays the contents of a particular RMX/80 
system list. For example, the command V R displays the current contents of the 
Ready List. 



Format. 



V < 



T 
E 
R 
S 
D 

M (expression] 
W §expr€!Ssion§ 



I 



Description. With the passive Debugger, an option must always be specified. If the 
M or W option is selected, it must be follov/ed by an expression which specifies the 
address of an Exchange Descriptor. 
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The VIEW command options have the following meanings: 

T = Task List; a list of all tasks in the system. 

E = Exchange List; a list of all exchanges in the system. 

R = Ready List; a list of all tasks currently on the Ready List. 

S = Suspend List; a list of all tasks currently suspended. 

D = Delay List; a list of all tasks currently in a timed wait. 

M = Message List; a list of all messages queued at a particular exchange. 

W = Wait List; a list of all tasks queued at a particular exchange. 

no entry = Ready, Suspend, Delay, Wait, and Message lists. 



The VIEW command generates displays of lists of addresses. These lists provide 
useful information about the state of the system. For example, the V S command 
lists the Task Descriptor addresses of all currently suspended tasks. 



The general format of the VIEW command display is as follows: 



cL=xxxx, . . .,xxxx 

The lower-case c is replaced by the lis ; option specified in the VIEW command. 
Thus, the display for a V R command logins with the characters RL= to indicate 
that the display is for the Ready List. 1 ach xxxx is replaced by the address of the 
Task Descriptor of a ready task. 

The VIEW command produces one other important piece of data: when displaying a 
list of Task Descriptor addresses, the VIEW command places an asterisk after the 
address of a Task Descriptor if that task has had a stack overflow or stack full con- 
dition since the last time the system was restarted. This feature is an aid in determin- 
ing stack size requirements, as discussed in Chapter 3. 

With the passive Debugger, the V M and V W commands require the use of an ex- 
pression that yields the address of an exchange. The Debugging issues an IN- 
VALID ADDRESS message if the expression does not yield a valid Exchange 
Descriptor address. 



When the VIEW command is executed, a high-priority Debugger task takes a "snap- 
shot" of the requested list(s) and then gives control to a lower-priority task whose 
responsibility is to display the list(s). The high-priority task will cause a slight 
increase in interrupt latency. The displayed list(s) may be obsolete by the time the 
display is completed, because the system continues to run. 



With the active Debugger, you are not required to include the address of an ex- 
change in the VMorVW commands. You may, of course, use this option to view 
the tasks or messages waiting at a particular exchange. When no expression is given, 
the Debugger provides a display for each Exchange Descriptor in the system. The 
display format is somewhat modified to indicate the exchange being displayed: 



cL(yyyy)=xxxx, . . .,cL<yyyy)=xxx:<, . . .,xxxx; . . . 

The lower-case c is replaced by an M or a W, depending on which command you 
entered; yyyy is replaced by the address of the Exchange Descriptor being displayed; 
and xxxx is replaced by the address of a message or Task Descriptor queued at the 
exchange. 



With the active Debugger, you can enter i V command without any options. The 
Debugger displays the Ready List, Suspend List, and Delay List, the Wait lists, and 
the Message lists. 
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NOTE 

A single VIEW command never displays more than 100 addresses. Thus, ; 

V W, V M, or (particularly) a V command might not display all the Wait or 
Message Lists. The V E command reveals this situation when it occurs, since 

V E then lists more exchanges than displayed by the earlier V command. 
You can use additional V W or V M commands to display the remaining 
Wait or Message Lists by requesting them one at a time. 



FORMAT Command. 

Function. The FORMAT command formats and displays the contents of a Task 
Descriptor, Exchange Descriptor, or message. 



Format. 



T [expression] 
E [expression] 
M expression 



Description. The expression in an F T (Format Task Descriptor) command must 
yield the address of a Task Descriptor. Similarly, the expression in an F E (Format 
Exchange Descriptor) command must yield the address of an Exchange Descriptor. 
The Debugger issues an INVALID ADDRESS message if the expression is 
improperly stated. 



The expression in an F M (Format Messag e) is not checked for validity. The Debugger 
will format whatever data happens to begin at the specified location as a message. 
However, you should be certain that the expression yields an address that is valid 
within your system. You must not instruct the Debugger to fetch data from memory 
that is not used in your system. 

With the active Debugger, it is not necessary to enter an expression with an F T or 
F E command. In this case, the Debugger displays the first Task Descriptor or Ex- 
change Descriptor, depending on the command, on its list of Task or Exchange 
Descriptors. When no options are specified, the next descriptor in the current list is 
displayed. If all the descriptors on a list have been displayed, the Debugger issues an 
error message and then issues a prompt for another command. 



Formatted Task Descriptor Display. The Debugger formats the fields of a Task 
Descriptor in the same order as described under "Details of System Operation" in 
Chapter 2. The Debugger adds three fields: the first display field specifies the ad- 
dress of the Task Descriptor; the last two display fields contain the task name and 
the number of bytes remaining on the task 's stack, respectively. 



The format is as follows: 



l| n ,i Ail 

N 

BlatuafPi 



TDA DLF DLB THRD DLY EDA SP MARK SIP NA TL NAME STKLFT 

xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx AAAAAA yyyy 

4 ^ Remaining Stack 

■ Task Name 
Task Link 
Name Address 
Status /Priority 

Merker 
Stack Pointer 
Exchange Desci iptor Address 
Delay/Message 

Thread 
Delay Link Back 
Delay Link Forward 
Task Descriptor Address 
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The STKLFT field indicates the number of never-used bytes remaining in the stack 
when this FORMAT command is executed. 

You can determine whether a task is suspended (or preempted or delayed) by look- 
ing at the status bits (leftmost two digits of the S/P field). You can determine if the 
task is waiting by noting the EDA field, then using the VIEW command to check the 
waiting task list at that exchange. 



Formatted Exchange Descriptor Display. The Debugger formats the fields of an Ex- 
change Descriptor in the same order as described under "Details of System Opera- 
tion" in Chapter 2 of this manual, with one exception: the first display field specifies 
the address of the Exchange Descriptor. 

The format is as follows: 



EDA MH MT TH TT EL 

xxxx xxxx xxxx xxxx xxxx xxxx 

If f I Exchange Link 

Task Tail 
I Task Head 

Message Tail 
Message Head 
Exchange Descriptor Address 



Formatted Message Display. The Debugger formats the fields of a message in the 
same order as described under "Message Coding" in Chapter 2 of this manual, with 
one exception: the first display field specifies the address of the message. 

The format is as follows: 



MDA LINK LEN TYPE HEA REA REM 

xxxx xxxx XXXX XX xxxx xxxx XX XX XX XX XX XX XX XX 

XX XX XX XX XX XX XX 



t 

H( 

Type 
Length 

Link 

Message Address 



t ♦ 

Re 



Remainder 
Response Exchange Address 
Home Exchange Address 



A message display is limited to 20 lines of text or 160 bytes of the Remainder field. 
You can terminate this display by entering a control-C. Control-C terminates the 
display at the end of the current line. 



QUIT Command. 



Function. The QUIT command terminates the debugging session. Notice that all 
terminal input is directed to the Debugger during a debugging session. The QUIT 
command directs all subsequent terminal input to your system rather than to the 
Debugger. 
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Format. 
Q 



Description. The QUIT command has no options. 

Although the QUIT command terminates this debugging session, the Debugger re- 
mains available for use. You need only enter a control-C to re-activate the Debug- 



NOTE 

The Terminal Handler provides controls to prevent user output to the ter- 
minal during a debugging session. These controls should usually be reversed 
when the debugging session is terminated. If control-S has been used to 
delay user output, control-Q resumes the output. If control-O has been used 
to discard user terminal output, another control-O resumes the output. 



NOTE 

All the remaining Debugger commands apply only to the active Debugger. 
Attempting to use any of the following commands with the passive Debug- 
ger causes a syntax error message. 



EXECUTE Command. 



Function. The EXECUTE command allows you to execute, on command, a pro- 
cedure in memory including any of the RMX/80 operations or a user-supplied pro- 
cedure. 



Format. 

X procedure-address [(parameter-1 , . . ., parameter-n)] 



Description. The procedure-address in an EXECUTE command may be the address 
of an RMX/80 operation or of one of your own system's procedures. Parameter re- 
quirements, if any, depend on the procedure being called. As examples, the RQ- 
SEND operation requires two parameters (an exchange address and the address of 
the message to be sent); but the RQDTSK operation requires only one (the address 
of the Task Descriptor to be deleted). All parameter passing conforms to the rules 
for calling a PL/M procedure from an assembly language program module. (Refer 
to "Parameter Passing and Returned Values" in Chapter 3.) "Procedure-address" 
may be the address of an assembly language subroutine, provided that the PL/M 
parameter passing conventions (as defined under "Parameter Passing and Returned 
Values" in Chapter 3) are followed. 

The EXECUTE command sets up the parameters provided, and then calls the pro- 
cedure. Upon return from the called procedure, the task registers contain any values 
returned by the called procedure, and the Breakpoint Task becomes undefined (BT 
=0). The Breakpoint Task is explained under the CHANGE command. The values 
returned can be displayed by using the task -register version of the DISPLAY com- 
mand. 
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The EXECUTE command can be used to execute RQSUSP, in order to suspend tasks 
irrelevant to the part of the system you are trying to debug. This has the advantage of 
simphfying the system. However, you must be certain that the RQSUSP operation is 
available. RQSUSP is not normally linked into the system as part of the RMX/80 
Nucleus; the operation is available only if you use it in one of your tasks or explicitly 
link it into your system. 

For the iSBC 80/10 version, note the restriction that if the Debugger's priority is in 
the range to 128, the EXECUTE command should not be used. 



DEFINE Command. 

Function. The DEFINE command allows you to assign PL/M-like symbols 
(numeric variables) to frequently-used memory addresses or other numeric values. 

Format. 

D numeric-variable = expression 

Description. The ability to assign symbolic names to frequently-used addresses is 
particularly useful in debugging, since many of these addresses change each time the 
system is relinked and relocated. The DEFINE command allows you to refer to these 
addresses using PL/M-like symbols, which are easier to remember than addresses 
and which need not change as the program changes. All you need do is enter the ap- 
propriate DEFINE commands at the beginning of each debugging session. 

"Numeric-variable" is an identifier. This identifier must conform to rules that fall 
part-way between PL/M and assembly language. The identifier must begin with a 
period and must not exceed six characters, not counting the initial period and any 
dollar signs. The first character must be alphabetic, and the remaining characters 
may be either alphabetic or numeric. 

A system can have up to 30 numeric variables at any given time. 

The expression in the format should yield an address or other value meaningful to 
you in debugging. The DEFINE command allows you to retain the same symbolic 
name from session to session, providing the system continues to run and is not 
restarted. 

The DEFINE command does not allow duplicate numeric variable symbols. The 
Debugger issues a DUPLICATE SYMBOL message if you try to define the symbol 
more than once. The CHANGE command allows you to assign a new address to a 
numeric variable defined in this debugging session. 

REMOVE Command. 



Function. The REMOVE command allows you to remove a previously-defined 
numeric variable from the system. Thus, the REMOVE command is associated with 
the DEFINE command, previously described. 



Format. 

Z [numeric-variable] 
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Description. As in the DEFINE command, "numeric-variable" must be a PL/M- 
like symbol. If no such symbol has been defined, the Debugger issues an error 
message followed by a prompt for a new command. 

A Z (REMOVE) command without any parameter removes all previously defined 
numeric variables from the system. Obviously, care must be taken when issuing Z 
without a parameter. 



Debugger Breakpoint Feature. The final four commands — CHANGE, 
DISPLAY, GO, and SCAN — are concerned with the Debugger breakpoint feature. 
To clarify the descriptions of these commands, a general explanation of Debugger 
breakpointing is provided here. 

The Debugger provides eight breakpoint registers, which are identified by the sym- 
bols BO, Bl, . . ., B7. Each breakpoint register may be used to store the address of 
an instruction or exchange that is to cause a breakpoint. The breakpoint-register for- 
mat of the CHANGE command allows you to set, change, or clear a breakpoint. 

The Debugger recognizes three types of breakpoints: execution breakpoints, send 
breakpoints, and wait breakpoints. An execution breakpoint occurs when a task ex- 
ecutes an instruction whose address is specified in a breakpoint register. A send 
breakpoint occurs when a task sends a message to a specified exchange. A wait 
breakpoint occurs when a task waits at a specified exchange and subsequently 
receives a message. Send and wait breakpoints are also referred to as exchange 
breakpoints. 

When a breakpoint occurs, the Debugger temporarily removes from the system the 
task that caused the breakpoint and issues a display message to the terminal in order 
to identify the breakpoint (by register) and the task. If the breakpoint register was 
set specifying the Continue option, the task is automatically returned to the system 
after the output message is issued. If the Continue option was not specified, the task 
remains outside the system until you restart it from the terminal with the GO com- 
mand. 

Each time an execution breakpoint occurs, the Debugger cancels the breakpoint by 
resetting the breakpoint register to zero and restoring the breakpointed instruction 
to its original state. Unlike execution breakpoints, however, exchange (send or wait) 
breakpoints are not reset each time a break occurs. 

The Debugger suspends tasks not by using the RQSUSP operation, but by placing 
their Static Task Descriptor addresses on a list of its own called the Breakpoint List. 
This list is similar to the RMX/80 Suspend List in that it removes the task from 
contention for system resources. The Breakpoint List includes all tasks that have 
incurred breakpoints (without the Continue option) and have not yet been resumed, 
and also any tasks that have incurred a stack overflow while an overflow scan was in 
effect (see description of the SCAN comman d). Each task on the Breakpoint List has 
a state — Execute, Wait, Send, or Overflow. The first three states correspond to the 
type of breakpoint, and the last designates a stack overflow detected by the SCAN 
command. 

You may designate one task on the Breakpoint List as the Breakpoint Task. Doing 
this (via the breakpoint-task format of the CHANGE command) enables you to ex- 
amine and alter the contents of that task's registers, which are stored on the task's 
stack. You use the task-register format of the DISPLAY command to display the 
contents of one or more task registers, and the task-register format of the CHANGE 
command to alter the contents of a task register. 
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You may resume a task on the Breakpoint List by making it the Breakpoint Task 
and then using the GO command. (This is true of tasks that have incurred a stack 
overflow detected by SCAN as well as those that have incurred breakpoints.) 



NOTE 

There are two differences between the RMX/80 Debugger execution break- 
points and ICE-80 or ICE-85 breakpoints that may cause confusion. Both 
of these differences are based on the fact that the RMX/80 Debugger 
replaces the first byte of the instruction to be breakpointed with an RST 5 
instruction. The following conditions should be noted: 

• Setting a breakpoint at the location of the breakpoint just incurred and 
then continuing (with the Go Command) will always result in the task 
incurring another breakpoint. 

• If RMX/80 "crashes" while an execution breakpoint is set, the RST 5 
will be left in the code. The code must, therefore, be "patched" with 
the original instruction, or the program must be reloaded. 



CHANGE Command. 

Function. The CHANGE command allows you to establish or change a breakpoint, 
define a Breakpoint Task, alter the Breakpoint Task's registers, or change the value 
of a numeric variable previously entered via a DEFINE command. 



General Formats. 



breakpoint-register 



BT 

task-register 
numeric-variable 



expression 



zero-expression 



expression 



rr E[c] ~, 

rw[cn 

LS[C] J 



Description of Breakpoint-Register Format. 

(expression 
zero-expression 

The ellipsis in the format specifies that the indicated portion of the format may be 
repeated. In practice, this means that both S and W options may be specified in one 
command. The C option, if present, must not be separated by a space from the E, 
W, or S which precedes it. 

This format sets or clears a breakpoint, using one of the eight breakpoint registers. 

"Breakpoint-register" must be the symbol for a breakpoint register (BO, Bl or 

B7). To set a breakpoint, you specify, after the equals sign, an expression that 
yields the address of an instruction or an Exchange Descriptor — followed by a 
code for the type of breakpoint— E (execution), S (send), W (wait). To cancel a 
previously set breakpoint, you specify a zero-expression (an expression that yields 
zero). 
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The breakpoint codes have the following meanings: 

E: Execution breakpoint — break when the specified instruction is executed. 

W: Wait breakpoint (an exchange breakpoint)— break when a task is removed from 
the specified exchange. 

S: Send breakpoint (an exchange breakpoint) — break when a task sends a message 
to the specified exchange. 

As mentioned previously, the Debugger temporarily removes from the system a task 
that causes a breakpoint. The Continue (C) option, which applies to the particular 
E, W, or S option immediately preceding it, allows the breakpointed task to resume 
contention for system resources automatically, as soon as a display message has 
been sent to the terminal. When this option is not specified, the task remains outside 
the system until you restart it by using the "BT=" format of the CHANGE com- 
mand and a GO command. 

For an execution breakpoint, "expression" must yield the address of an instruction 
in RAM. The Debugger places a RESTART instruction at this address. (The 
Debugger also saves the original contents of this address so that the instruction 
can be restored when the breakpoint is (Cancelled.) The expression must yield 
the first byte of the instruction; if the RESTART instruction is embedded within a 
multi-byte instruction, the instruction will malfunction when executed. Each time 
an execution breakpoint occurs, the Debugger cancels the breakpoint by resetting 
the breakpoint register to zero and restoring the breakpointed instruction to its 
original state. 

An execution breakpoint generates the following display on the terminal: 
Bn , E[C] ,TDA=xxxx 

If the Debugger is not active when a task incurs a breakpoint, the Debugger is 
automatically activated (as if control-C were struck). The n specifies the number of 
the breakpoint register; E identifies an execution breakpoint; the C appears only if 
the Continue option was specified for this breakpoint; xxxx is replaced by the ad- 
dress of the Task Descriptor of the task that caused the breakpoint. 

For the iSBC 80/10 version, note the following restriction: if a task which has a soft- 
ware priority in the range to 128 is breakpointed with an execution breakpoint, it 
should not be resumed. Resuming such a task may cause incorrect execution. 

For an exchange (send or wait) breakpoint, a W, S, or both may follow the expression. 
The expression must yield the address of an Exchange Descriptor, or an error 
message is generated. If W is specified, any task that receives a message or times 
out after performing an RQWAIT at the specified exchange is breakpointed. If 
S is specified, any task that performs an RQSEND to the exchange is breakpointed. 
Unlike execution breakpoints, exchange breakpoints are not reset each time a 
break occurs. Note that both the W and S breakpoint types may be specified for 
the same exchange breakpoint. If neither breakpoint type is specified, W is assumed. 

Several additional restrictions apply to exchange breakpoints. 

• A task that performs an RQACPT at a breakpointed exchange always receives a 
zero return value. 

• An RQSUSP operation for a task waiting at a breakpointed exchange is 
ignored. 

• An RQRESM operation for a task waiting at a breakpointed exchange causes 
the breakpoint facility to malfunction. 

• An S type breakpoint should not be specified for an interrupt exchange. 
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• Use the VIEW command to examine the message list or task list of a 
breakpointed exchange. A FORMAT or MEMORY command used for this pur- 
pose will display breakpoint control structures rather than the actual message or 
task list. 

• An exchange breakpoint does not detect a task that performs an RQWAIT with 
a time limit of one time unit if the wait times out before a message is sent to the 
exchange. 

• Exchange breakpoints increase both the interrupt latency and the total load on 
the system. In extreme cases, this may cause a missed interrupt. 

An exchange breakpoint generates the following display on the terminal: 
Bn, | s' J [C],TDA=xxxx,MSGA=aaaa 

If the Debugger is not active when a task incurs a breakpoint, the Debugger is 
automatically activated, and the display above is given followed by the Debugger 
prompt. The n specifies the number of the breakpoint register; W or S appears 
depending on whether the breakpoint was for a wait or a send; the C appears only if 
the Continue option was specified for this breakpoint; xxxx is replaced by the ad- 
dress of the Task Descriptor of the task that caused the breakpoint; aaaa is replaced 
by the address of the message sent to or received from the breakpoint exchange. 

Description of Breakpoint-Task Format. 
BT=expression 

This format of the CHANGE command allows you to select a particular task from 
the Breakpoint List as the current Breakpoint Task. (Note that there may be only 
one Breakpoint Task at a time.) The expression must yield the address of a Task 
Descriptor on the Breakpoint List. (The DISPLAY command can display the current 
contents of the list.) An error message is generated if the expression does not yield 
the address of a Task Descriptor on the Breakpoint List. 

When the Debugger removes a Breakpoint Task from the system, it performs a con- 
text save, thus preserving the contents of the task's registers. The DISPLAY com- 
mand gives you access to the current Breakpoint Task's registers. The "task-register 
= expression" format of the CHANGE command allows you to alter those registers. 
For execution breakpoint tasks, all the the registers may be meaningful and are 
displayed as they were when the breakpoint occurred. For exchange breakpoints, 
only the Stack Pointer and Program Counter registers are meaningful, since the 
other registers are modified in the RQWAIT and/or RQSEND operations. These 
other registers all contain zeros. Also, the Program Counter always contains the ad- 
dress of the next instruction after the RQWAIT or RQSEND operation. For break- 
points caused by a stack overflow (see the SCAN command), none of the registers 
are meaningful, so they are all set to zeros. 

A task must be designated as the current Breakpoint Task before the GO command 
(described later in this chapter) can be used to return it to the system. 

Description of Task-Register Format. 

task-register=expression 

This format of the CHANGE command updates the contents of the specified Break- 
point Task register with the value of the expression. For exchange breakpoints, 
altering any register other than the Stack Pointer or Program Counter has no effect. 
For overflow breakpoints, altering a register has no effect. 
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Task-register must be one of the following values: 

RA A register (accumulator) 

RB B register 

RC C register 

RD D register 

RE E register 

RH H register 

RL L register 

RF Flags 

RPCH High-order byte of Program Counter 

RPCL Low-order byte of Program Counter 

RSPH High-order byte of Stack Pointer 

RSPL Low-order byte of Stack Pointer 

RBC B and C register pair 

RDE D and E register pair 

RHL H and L register pair 

RPC Program Counter 

RPSW Program Status Word (accumulator and flags) 



Description of Numeric-Variable Format. 

numeric-variable=expression 

The DEFINE command allows you to assign symbolic names to addresses required 
during debugging sessions. This format of the CHANGE command allows you to 
alter the value assigned to a previously-defined numeric variable. An error message 
is generated if "numeric- variable" is rot previously defined. The format of 
"numeric-variable" is as described under the DEFINE command. 



DISPLAY Command. 

Function. The DISPLAY command generates displays of various Debugger struc- 
tures associated with Breakpoint Tasks, and the values of symbols assigned via the 
DEFINE command. You do not enter an op-code to invoke the DISPLAY com- 
mand; instead, you simply enter the name of the item to be displayed. 



Format. 



breakpoint-register 

BT 

BL 

B 

R 

task-register 
numeric-variaole 
no entry 



Description. To specify one of the breakpoint registers, enter the name of the 
desired register, BO, Bl, . . ., B7. The DISPLAY command generates the following 
display on the terminal: 

Bn=xxxx op op 
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The n in the display is replaced by the number of the specified breakpoint register; 
xxxx is replaced by the address currently associated with this breakpoint register (0 if 
the breakpoint is currently reset); op is replaced by the symbols for a breakpoint op- 
tion, as explained under the CHANGE command. 



Enter BT to display the address of the current Breakpoint Task's Task Descriptor. 
The DISPLAY command generates the following display: 



BT=xxxx(s) 



The xxxx in the display is replaced by the address of the Task Descriptor of the cur- 
rent Breakpoint Task (0 if there is no current Breakpoint Task). The s is replaced by 
one of the following letters to indicate the task's status: O = Stack Overflow; E = 
Executing; W = Waiting; and S = Sending. 



Enter BL to display the entire Breakpoint List. The Breakpoint List contains the 
Task Descriptor address and current status of each breakpointed task. The display 
has the following format: 

BL=xxxx(s),xxxx(s), . . .,xxxx(s) 



Each xxxx(s) is replaced with the Task Descriptor address and status (Stack 
Overflow, Executing, Waiting, or Sending) of a breakpointed task. 



Enter B to obtain a display of all the Breakpoint Registers followed by the Break- 
point Task address and a display of the Breakpoint List. The display has the follow- 
ing format: 

B0=xxxx op op 
B1=xxxx op op 



B7=xxxx op op 
BT=xxxx(s) 

BL=xxxx(s),xxxx(s), . . .,xxxx(s) 



Enter R to obtain a display of the current Breakpoint Task's registers. The display 
has the following format: 



RA=xx,RF=xx,RBC=xxxx,RDE=xxxx,RHL=xxxx,RPC= xxxx,RSP=xxxx 

4 Stack Pointer 

Program Counter 
H and L Registers 
D and E Registers 
B and C Registers 

Flags 

A Register (accumulator) 



:,nut=xxxx,HH 

t t 

Hi 
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In the display, xx and xxxx are replaced by current contents (in hexadecimal format) 
of the register or register pair. If desired, you can display the contents of any in- 
dividual register by entering a task-register name from the following list: 



RA 


A register (accumulator) 


RB 


B register 


RC 


C register 


RD 


D register 


RE 


E register 


RH 


H register 


RL 


L register 


RF 


Flags 


RPCH 


High-order byte of Program Counter 


RPCL 


Low-order byte of Program Counter 


RSPH 


High-order byte of Stack Pointer 


RSPL 


Low-order byte of Stack Pointer 


RBC 


B and C register pair 


RDE 


D and E register pair 


RHL 


H and L register pair 


RPC 


Program Counter 



RPSW Program Status Word (accumulator and flags) 

Enter the name of a numeric variable (see DEFINE command) to obtain its current 
value. The display has the following format: 

.abcdef=xxxx 

In the display, .abcdef is replaced by the name of the numeric variable; xxxx is 
replaced by the value currently assigned to the numeric variable. 

To obtain a display of the current values of all currently defined numeric variables, 
strike the Carriage Return without making any other entry. Because numeric 
variables are commonly used to assign symbolic labels to frequently used addresses 
in a debugging session, this option provides a handy reminder. If there are no cur- 
rently defined numeric variables, the display consists only of another prompt. 



GO Command. 

Function. The CO command resumes the Breakpoint Task — i.e., makes it ready to 
run again. 

Format. 
G 



Description. Options are not permitted with the GO command. 

The GO command resumes the Breakpoint Task by removing it from the Breakpoint 
List and returning it to the system, so that it becomes ready to run again. When it 
becomes the highest priority ready task, it v/ill begin running at the next instruction 
that was to be executed when the break occurred. 

As a side effect, the GO command causes the Breakpoint Task to become undefined 
(BT=0). 

If the GO command is executed when there is no Breakpoint Task, the Debugger 
issues an error message and issues a prompt f or another command. 
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See the description of the CHANGE command for a description of how to set a 
breakpoint. 



SCAN Command. 

Function. The SCAN command periodically checks the Task Descriptors of all 
tasks in the system to determine whether any task's stack has an overflow condition. 
If one is found, the SCAN command issues an overflow message to identify the task 
with the overflow condition. 

Format. 

S [expression] 

Description. The expression in the SCAN command serves two purposes. When 
provided, the expression specifies the frequency of the scan. Termination of the scan 
is accomplished by omitting the expression. 

The expression specifies the number of system time units between scans. (A system 
time unit is 50 msec in the iSBC 80/20, 80/24, or 80/30 version. Thus, an expression 
with the value 20 specifies a scan once each second. On the iSBC 80/ 10, the length of 
a system time unit may vary; refer to Appendix G.) If the value of the expression is 
too great, a stack overflow may cause a fatal system malfunction before the 
Debugger detects the overflow. If the value of the expression is too small, the scan 
may occur so frequently that it interferes with the operation of the system. Fortun- 
ately, the interactive nature of the Debugger allows you to change the scan rate at any 
time. Therefore, it is better to start with a frequent scan rate so that you are more 
likely to catch any stack overflow. If the scan rate seems to interfere with the system's 
performance, you can alter the rate. 

When the SCAN command detects a stack overflow, it generates the following 
display on the terminal: 

OVERFLOW,TDA=xxxx 

TDA stands for Task Descriptor Address; xxxx is replaced with the address of the 
Task Descriptor for the task with the stack overflow. 

The SCAN command removes from the system a task with stack overflow by adding 
it to the Debugger's Breakpoint List. You can resume execution of the task with the 
GO command . 

The SCAN command cannot suspend a task that is waiting at an exchange, since this 
might destroy synchronization in some systems (for example, when two tasks alter- 
nately wait at the same exchange). Instead, the SCAN command issues the message 
MORE OVERFLOW(S). As soon as the task's wait is satisfied, the SCAN com- 
mand moves the task to the Breakpoint List and issues an overflow message. Use the 
VIEW command to determine which tasks have the overflow condition. Because of 
the treatment of waiting tasks, the SCAN command may have residual effects even 
after you terminate the scanning process. If the scan detects a waiting task with an 
overflow but you terminate the SCAN command before a message can be issued, the 
task is moved to the Suspend List when its wait is satisfied. You can detect this con- 
dition with the VIEW command. 

You can leave the SCAN command in effect even when you terminate a debugging 
session (see the QUIT command). If an overflow is detected, the SCAN command 
activates the Debugger. This allows the SCAN command to display the appropriate 
message(s) and also allows you to enter a response through the terminal. 
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Error Messages 

After you enter a command line, the Deb agger checks the command for any errors. 
When an error is detected, the Debugger aborts the processing of the command, 
issues an error message, and then issues a prompt for a new command. 

The Debugger recognizes three general types of errors: 

• Syntax errors caused by the incorrect specification of a command. 

• Semantic errors caused by such things as an expression yielding an invalid 
address. For example, certain expressions must yield the address of a Task 
Descriptor. 

• Processing errors detected during the execution of a command. For example, 
symbol table space may be exhausted. 

An error message consists of two lines: 

1. The erroneous line up to the point of the error. A Crosshatch (#) follows the 
character where the Debugger detected the error. 

2. A message describing the error. The following is a complete list of messages 
generated by the Debugger: 

SYNTAX ERROR 

INVALID ADDRESS 

DUPLICATE SYMBOL 

NOT FOUND 

TABLE FULL 

NO BREAKPOINT TASK 



Suggestions for Debugging Your System 

Debugger Priority. You must choose the' priority at which the Debugger runs. 
Commonly, the Debugger is assigned a priority lower than user tasks. In complex 
systems, this may not provide adequate Debugger response times. Some experimen- 
tation may be required to find a priority that provides adequate response time 
without seriously affecting the performance of the application software. 



A Systematic Approach to Debugging a New System. As mentioned previously, 
the Debugger runs under the RMX/80 Nucleus and requires the services of the Ter- 
minal Handler. By implication, the Debugger requires at least a minimally opera- 
tional system. If your tasks force the system into an unrecoverable error, the Debug- 
ger also becomes inoperative. (ICE-80 or ICE-85 may be used in this situation.) 

If you have already implemented the Demonstration System, then the RMX/80 
Nucleus, Terminal Handler, and Debugger have already been tested in your hard- 
ware environment and are fully operational. The Debugger allows you to add your 
tasks to the system one by one. You must do this carefully. 

First, you add your application task with the highest priority. Keep in mind that 
RMX/80 always gives control to the highest-priority task when the system is in- 
itialized (each time the system is restarted). When none of your application tasks is 
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included in the Initial Task Table, the highest-priority task is always a pre-tested 
RMX/80 task. Therefore, the system must be operational. (Actually, nothing is run- 
ning, since all RMX/80 tasks are waiting to service one of your tasks or an interrupt. 
The system simply enters a HALT state.) The active Debugger's EXECUTE (X) 
command allows you to enter an RMX/80 RQCTSK operation. Use this operation 
to activate your highest-priority application task. 

Using the Debugger EXECUTE command, enter the addresses of the RQCTSK 
operation and the Static Task Descriptor for your highest-priority task. At this 
point, all the RMX/80 tasks are waiting to service your application tasks, but only 
one of your tasks exists in the system. Your highest priority task should "run to 
completion" — in other words, until it waits at an exchange, suspends itself, or 
deletes itself. 

Now you must decide which task to activate next. Typically, this will be the second 
highest-priority user task, since RMX/80 schedules tasks for execution by priority. 
In effect, you are manually simulating RMX/80's startup procedure. This puts you 
in the position of making decisions normally handled by RMX/80. This also gives 
you a tremendous advantage when debugging: if the system fails as you add your 
tasks to the system, you know which task directly or indirectly caused the problem. 

Using the Debugger to Improve System Performance. Using the Debugger in an 
operational system can be especially useful for "fine-tuning" the system. For exam- 
ple, you may find that a particular exchange frequently has a relatively large number 
of messages queued. Raising the priority of the task(s) that service the exchange may 
improve overall system performance. Similarly, when a message-consuming task 
spends too much time waiting for a message, system performance may be improved 
by raising the priority of the message-producing task(s). 

Tips on Real-Time Debugging. Certain practices will be helpful to you as you 
debug your system: 

• Become thoroughly familiar with all the Debugger commands. 

• Use figure 2-8 as a reference during debugging. 

• Keep a list of commonly used addresses, including the addresses of the RMX/80 
operations and of your system's Task Descriptors and Exchange Descriptors. 
Those addresses that are public (the addresses of RMX/80 operations and 
PUBLIC exchanges) are supplied in the output from the ISIS-II LOCATE pro- 
gram. Addresses that are not public can be obtained by using the Format Task 
Descriptor (FT) option of the FORMAT command. 

• Use the DEFINE command to assign symbols to commonly used addresses. 

The most common cause of system failure is writing over a system structure. This 
kind of failure can be quite subtle. To cite an unlikely example, your program might 
over-write a Task Descriptor's Stack Pointer address of 3230H with the data 3130H. 
Such an error might allow the system to run indefinitely without a failure. In 
general, the Debugger cannot detect such a logic error in an application program; 
however, the Debugger can detect a stack overflow, a likely side effect of the above 
problem. 

Always keep in mind that your application system continues to run while you use the 
Debugger. Thus, the Debugger always displays memory as it was when the display 
was requested; therefore, Debugger displays are always somewhat behind what is 
actually happening in the system. This is especially important to remember if you 
modify memory. For example, you might format and display a message. If you 
decide to alter some portion of the message, it is quite possible that the system will 
write a different message into the same memory before you can enter your modifica- 
tion. The Debugger breakpoint facility and the X (Execute) command can be used 
to restrict the dynamic nature of the system. 
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On the subject of modifying memory, there are, of course, certain fields that you 
should never modify. Most of these are simply a matter of common sense. For ex- 
ample, you should not modify the various linkage fields supplied by RMX/80. (The 
Delay Link Forward, Delay Link Back, and Status fields of the Task Descriptor and 
the Link field of a message are prime examples.) A less obvious example is the 
Priority field of the Task Descriptor. Keep in mind that tasks are queued onto the 
Ready List according to priority. If you Eilter the priority of a task already on the 
Ready List, you may destroy the order of the list. (Task priority is considered only 
when a task is being entered on the list. RMX/80 cannot tell if you change the priori- 
ty of a task already on the list.) An out-of -sequence Ready List can seriously affect 
system performance. 

You must also remember that a memory change in a debugging session does not 
affect your system except during that session. If you want to make the change 
permanent, you must alter your source program(s) and recompile or reassemble, 
link, locate, and test the resulting object file. 



Examples of Debugger Command Usage 

Setting an Execution Breakpoint. Assume that a task is executing code in RAM 
between the addresses E242H and E2F0H . (The RAM may be either in the iSBC 
system or in a portion of the Intellec Development System used to emulate iSBC 
memory.) The following commands set breakpoints for the instructions at addresses 
E250 and E263: 

B0=E250 E 
B1=E263E 

The Debugger removes the task from the system if it attempts to execute either of 
these instructions. For example, assume that the task has its Task Descriptor at 
C100H. If the task attempts to execute the instruction at E263, the Debugger issues 
the following message: 

B1,E,TDA=C100 

The following command makes this task the Breakpoint Task: 

BT=C100 

Making a task the Breakpoint Task allows you to interact with the task. For exam- 
ple, you might enter the following DISPLAY command to examine the contents of 
the task's registers: 

R 

At this point, you might decide to zero the task's accumulator and then return it to 
the system with the following commands: 

RA=0 
G 



Setting an Exchange Breakpoint. Assume that there is an Exchange Descriptor at 
location B212, and you want to breakpoint any task that waits for a message at that 
exchange. The following command sets the breakpoint: 

B4=B212W 
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Now assume that the task described in the previous example performs a wait at this 
exchange. When the task receives a message from this exchange, the Debugger 
suspends the task and issues the following message: 

B4,W,TDA=C1 00, MSG A=aaaa 

This message indicates that the task waiting at the Exchange Descriptor at B212 
received a message and has been removed from the system. 

Breakpointing Multiple Tasks. It is frequently useful to debug the interaction be- 
tween two tasks. Assume, for example, that two tasks communicate via the ex- 
change described in the previous example and you want to breakpoint them when a 
message is passed between them. You should specify: 

B4=B212S W 

Assume further that a task whose Task Descriptor is at A 100 waits at the exchange, 
and a task whose Task Descriptor is at A200 sends a message to the exchange. The 
Debugger removes both tasks from the system and issues the following messages: 

B4,S,TDA=A200,MSGA=aaaa 
B4,W,TDA=A100,MSGA=aaaa 

The first display indicates that the task whose Task Descriptor is at A200 performed 
a send to the breakpoint Exchange Descriptor and gives the address of the message. 
The second display indicates that the other task was removed from the system im- 
mediately after it received the same message. At this point, you can select either task 
to be the Breakpoint Task by naming the task's Task Descriptor in the "BT=" form 
of the CHANGE command. 



6-26 



CHAPTER 7 
DISK FILE SYSTEM 



General Description 

The Disk File System (DFS) provides disk access capabilities to RMX/80 users. 
(Throughout this chapter the term "disk" will occasionally refer generically to both 
Intel hard disk and diskette products.) The services are functionally similar to the 
disk facilities available in ISIS-II, although they operate in the real-time environment 
supported by RMX/80. Files may be created, deleted and changed; data may be 
accessed sequentially and directly ("randomly"). Many applications do not need all 
the services which DFS offers; the modular design of the system allows DFS functions 
to be implemented selectively, thereby keeping memory requirements consistent with 
the needs of the application. The Disk File System also gives the user the flexibility to 
configure various complements of Intel disk drives and controllers, again according to 
the needs of the application. 

DFS Capabilities 



Available Services. Table 7-1 summarizes the services offered by DFS. 



Table 7-1 . Disk File System Services 



SERVICE 


FUNCTION 


Data Transfer Services 


OPEN 

READ 

WRITE 

SEEK 

CLOSE 


Prepare a : ile for processing. 
Transfer d ata from an open file to memory. 
Transfer data from memory to an open file. 
Set or return value of disk file marker. 
Terminate processing of an open file. 


Directory Maintenance 
Services 


DELETE 

RENAME 

ATTRIB 


Remove a file from the directory and release its space. 
Change the name of a file in the directory. 
Change an attribute of a file in the directory. 


Other Services 


FORMAT 

LOAD 

DISKIO 


Initialize a new disk. 

Read a file of executable code into memory. 
Perform basic I/O operations. 



The data transfer and directory maintenance services are analogous to the cor- 
responding ISIS-II system calls, and disks processed with these DFS services will be 
compatible with ISIS-II. The file structure used by ISIS-II and DFS is described in 
Appendix E. DFS provides two additional capabilities not present in ISIS-II which 
significantly enhance the utility of the data transfer services: 
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1. An unlimited number of files can be open concurrently (subject to memory 
constraints). 

2. Multiple tasks may read the same file concurrently. 



The DFS LOAD service operates like the ISIS-II loader, except that control is passed 
to the loaded segment by the user task rather than by the loader. One way the loader 
can be used is to perform "overlay" processing, that is, to dedicate a memory space 
to transient routines that are loaded from disk into the memory space as needed. 

The FORMAT service labels (names) a disk and creates the directory and other 
system files needed for ISIS-II and DFS disk processing. Unlike ISIS-II, DFS has no 
file copying facility in its FORMAT service, so it cannot be used for disk backup. 
Any drive may be used to format a disk. 

A user task may bypass directory processing and perform I/O operations on the disk 
directly with the DFS DISKIO service. There is very little system overhead involved 
in this service, and any part of the disk may be read or written. On the other hand, 
the services that DISKIO provides are very basic. Comparing DISKIO to the 
directory-based services is somewhat like comparing assembly language to PL/M: 
power and "efficiency" are traded off for ease of implementation and maintenance. 
DISKIO is intended to be used primarily in applications that have extremely deman-" 
ding performance and/or memory constraints. 



Facilities for Real-Time Operation. DFS performs most of the activities required 
to manage real-time disk operations. The user does not have to be concerned with 
scheduling and coordinating the multiple and sometimes conflicting requests that 
typify real-time operations. By taking responsibility for these activities, and for the 
maintenance of system integrity, DFS encourages the user to concentrate on solving 
the application problem at hand. 

In addition to presenting a complex control situation, real-time applications often 
have demanding performance requirements. DFS helps maximize system 
throughput by allowing user tasks to overlap disk operations with processor opera- 
tions and by allowing multiple disk operations to proceed in parallel. For example, 
files can be "double buffered" so that while DFS is filling (or emptying) one buffer, 
the user task can be processing the data in the other, reducing the time the task 
spends waiting for I/O. If a system has more than one disk controller (iSBC 80/10's 
are limited to one controller), several controllers can be active at the same time, 
allowing concurrent access to multiple files. 



Device Independence. The Disk File System helps to isolate user tasks from the 
physical characteristics of specific disk drives and controllers. All references to hard- 
ware, such as recording density, are specified by the user in two or three tables. This 
allows user tasks to be written with minimal software consideration of hardware at- 
tributes. 



Modular Configuration. DFS is not a monolithic system; each user implements a 
"version" of the system which fits the requirements of the application. If the ap- 
plication has no need for direct access, for example, then the SEEK service is not in- 
cluded in the user's implementation of DFS. While this procedure slightly increases 
the initial effort involved in setting up a system, it insures that the memory required 
by DFS is a function of the application — no space is occupied by unused routines. 
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Use Environment 

The Disk File System operates on iSBC 80/20, 80/24, 80/30, and 80/ 10 computers. 
The system functions similarly on all the machines, and many applications developed 
on one machine can be run on the others, assuming compatible configurations. 

A variety of disk and diskette products can be used with DFS: two-platter hard disk 
units that record in single density, standard-size single-drive and dual-drive diskette 
units that record in either single or double density, mini-size diskette units that record 
in single density, and Intel controllers that can handle up to two or up to four drives. 

The minimum software environment for the Disk File System is the RMX/80 
Nucleus. Other RMX/80 extension tasks may be selected as desired. 



Memory Requirements 

Disk File System memory requirements vary with the level of support you need from 
DFS: more files, more controllers and more types of I/O operations generally in- 
crease the need for memory. Appendix D contains a complete breakdown of DFS 
memory requirements that can be used to calculate the memory needed to support a 
particular application. (Refer to "Confijruration Requirements" at the end of this 
chapter to determine what DFS tasks you need to implement a system with your 
particular requirements for controllers find services.) Appendix D also provides 
memory requirements for four sample system configurations, three of which include 
DFS. The third example illustrates how el minimal DFS directory-based system can 
be implemented in the iSBC 80/20 on-bosird ROM. 

DFS is unique among RMX/80 extensions in that some of its memory must be 
controller-addressable RAM. This is because disk transfers are performed by Direct 
Memory Access through the system bus. Because the RAM on the iSBC 80/20, 
80/24, and iSBC 80/10 boards is not connected to the bus, in 80/20-, 80/24-, and 
80/ 10-based systems off-board RAM must be used for certain DFS areas. On the 
iSBC 80/30, on-board RAM is connected to the bus, so this restriction does not 
apply. Note also that memory mapped to the Intellec development system via ICE-80 
or ICE-85 cannot be substituted for the controller-addressable RAM, since mapped 
memory is not accessible to the bus. 

Hardware Requirements 

The following Intel disk and diskette controllers, and Intel disk and diskette systems 
using these controllers, are supported by DFS: 

• iSBC201 Diskette Controller (1-2 drives) 

• iSBC 202 Double- Density Controller (1-4 drives) 

• iSBC 204 Diskette Controller (1-4 drives, either standard or mini-size) 

• iSBC 206 Hard Disk Controller (1-4 drives, 2 platters per drive) 

iSBC 80/20, 80/24, and 80/30 systems can use any number and mix of drives and 
controllers, subject only to the availability of interrupts and memory space. Systems 
using iSBC 80/ 10's are limited to a single controller and therefore to a maximum of 
two or four drives, depending on which controller is selected. 

If mini-size diskette drives are used on an iSBC 80/ 10-based system, an off-board 
clock must be configured in the system. (See Appendix G.) This is necessary because 
timed RQWAIT operations are used by DFS to start and stop the drive motor. The 
clock is also needed in an 80/10 system if you wish to use the timeout feature, 
whereby an error code will be returned if the drive has not responded within a set 
period of time. (See "Timing Variables for Disk File System" in Appendix G.) 

Note that disk controller boards must have higher bus priority than CPU boards. 
(See discussion of bus priority in Appendix F.) 
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How the Disk File System Operates 

The Disk File System is implemented as a set of tasks that run under the RMX/80 
Nucleus. User tasks communicate with DFS by sending messages to specific ex- 
changes. 

For example, sending a message to the RQOPNX exchange causes the DFS OPEN 
service to attempt to open the file specified in the request message. If the attempt is 
successful (i.e., no errors are detected), the OPEN service creates a new exchange to 
which subsequent messages requesting I/O to the file are sent. If another task opens 
the same file, DFS sets up a separate exchange for that task. Two tasks can access 
the same file through a single exchange if the opening task provides the exchange ad- 
dress to the other task. Using this approach is discouraged, however, since either 
task can change the file's LENGTH and MARKER indicators (see the discussion of 
LENGTH and MARKER which follows). In most cases it is better for two tasks 
which need access to the same file to send requests for access to a third task which 
does the I/O. Requests to READ, WRITE, SEEK, and CLOSE for different files 
are processed for the most part in parallel (see the discussion of controller exchanges 
which follows). READ, WRITE, SEEK, and CLOSE requests which are sent to the 
same exchange are processed serially. 

A separate exchange exists for each of the following DFS services: OPEN, 
RENAME, DELETE, ATTRIB, FORMAT, LOAD, and DISKIO. Requests for 
these services are queued at the appropriate exchanges and are processed serially 
first- in first-out (FIFO). Since these types of services are typically requested 
sporadically, their serial execution does not seriously impair the throughput of most 
systems. If a series of these requests (each a different type) must be executed in a 
guaranteed sequence, the requesting task must wait for each individual request to be 
acknowledged before issuing the next. 

Controllers are associated with tasks, and by implication, with exchanges. If two 
controllers are allocated separate tasks, they can be operated in parallel. If they are 
allocated the same task, only one controller can be active at a time, and requests to 
either controller are placed in the same queue and processed FIFO. The user 
specifies this controller/task relationship based on a throughput/memory tradeoff: 
separate tasks have higher throughput potential but require more memory than 
shared tasks. 



The paragraphs and figures that follow explain the operation of the individual DFS 
services. Note that although the diagrams show DFS as a single box, it is actually a 
collection of tasks. 



OPEN and CLOSE Services 

Figure 7-1 illustrates the task-exchange relationships that apply to the OPEN ser- 
vice. Tasks requesting a connection with a file send a request message to the DFS- 
defined OPEN exchange, RQOPNX. DFS returns a response message to a user- 
defined exchange, here called RESPSEX, and creates an active file request exchange 
(here called AFRSEX) through which the task and the file may communicate. Files 
may be opened for read, write, or update. 

The CLOSE service is invoked by sending a message to the active file request ex- 
change created when the file was opened. This service severs the task-file connection 
(shown by dotted lines in figure 7-1) when it is no longer needed. 
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Figure 7-1 . Exchanges for OPEN, CLOSE, READ, WRITE, and SEEK 



READ, WRITE, and SEEK Services 

The task-exchange relationships set up for the READ, WRITE, and SEEK services 
are the same as shown for OPEN (figure 7-1). After the file is opened, tasks perform 
these operations by sending request messages to the exchange created by the OPEN 
exchange (called AFRSEX in the figure). Since each task communicates with the 
open file through a "private" exchange, requests for I/O may proceed in parallel. 



DELETE, RENAME, and ATTRIB Services 

The task-exchange relationships set up for the directory services (DELETE, 
RENAME, and ATTRIB) are illustrated in figure 7-2. The user task sends a request 
message to the appropriate DFS-defined exchange for the service (RQDELX, 
RQRNMX, or RQATRX), then waits for a response from DFS at a user-defined 
response exchange (here called RESPSEX). Using these services, tasks may delete or 
rename files or change their attributes. As in ISIS-II, file attributes are Invisible, 
Write Protect, System, and Format. 



FORMAT and LOAD Services 

Figure 7-3 shows the task-exchange relationships that are used by the FORMAT and 
LOAD services. A user task may request that a disk be formatted by sending a re- 
quest message to the DFS-defined exchange RQFMTX. A task may request that a 
binary file be loaded into memory by sending a request message to the DFS RQLDX 
exchange. For either command, DFS sends a response message to a user-defined 
response exchange, called RESPSEX in the figure. 



DISKIO Service 

Users wishing to bypass the directory-oriented I/O service provided by DFS can 
access the disk in terms of tracks and sectors using the DISKIO service. All of the 
basic commands of the disk controller are available through this service. The 
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Figure 7-2. Exchanges for DELETE, RENAME, and ATTRIB 




Figure 7-3. Exchanges for FORMAT and LOAD 



7-6 



RMX/80 



Disk File System 



task-exchange relationships that pertain to DISKIO are shown in figure 7-4. The 
user task sends a request message to the DFS RQDSKX exchange, and DFS returns a 
response message to a user-defined exchange, called RESP$EX in the figure. 



Using the Disk File System 

In this section, two special topics — iSBC 80/10 interrupt polling and motor on/off 
operations for mini-size diskette drives — are discussed, followed by instructions for 
making requests for DFS services. At the end of the section, a list of DFS error codes 
is provided. 



iSBC 80/10 Interrupt Polling for DFS 

The Disk File System includes interrupt polling routines for the iSBC 80/ 10A and 
80/ 10B (see Chapter 2, "iSBC 80/ 10 Interrupts") for disk controllers, so your appli- 
cation does not need to supply these routines. However, each user task in any iSBC 
80/10 system must, as part of its initialization, do the following: 

• declare the applicable polling routines EXTERNAL, and 

• associate each with the appropriate interrupt level via an RQSETP operation. 

The names of the polling routines (procedure-addresses) are RQHD1 V for iSBC 201 
and 202 controllers, RQHD4V for iSBC 204 controllers, and RQHD6VforiSBC206 
controllers. The level-number in the RQSETP operation must be the interrupt level 
assigned to the controller task. 
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Figure 7-4. Exchanges for DISKIO 
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Motor On/Off Operations for Mini-Size Drives 

If your system includes mini-size diskette drives (supported by the iSBC 204 con- 
troller), you must request operations in your application tasks to turn the drive 
motor on and off. These operations are provided by the DISKIO service, which is 
described later in this chapter. 

Before attempting to access any file on a mini-size drive (i.e., before using any other 
DFS service that applies to that drive), your system must perform a DISKIO request 
specifying MOTOR ON. The MOTOR ON operation includes a one-second time 
delay, to ensure the drive motor is up to speed, before it returns. When all accesses 
are finished, your system must perform a DISKIO request specifying MOTOR OFF. 
The MOTOR ON and MOTOR OFF operations ignore the drive select on the 8271 
chip; so if two drives are connected to the same 8271 chip on the controller, both 
drives will be affected by a MOTOR ON or MOTOR OFF operation that specifies 
either of the drives. (Refer to "Drive Characteristics Table" in the configuration 
section of this chapter.) 

To conserve the lifetime of your drives, you may perform the MOTOR OFF opera- 
tion when you expect there will be no accesses to your mini-size drive (or pair of 
drives) for a reasonable period of time, then do another MOTOR ON operation 
before the next access request is made. (The length of a "reasonable" period of time 
depends upon your application, taking into consideration the tradeoff between drive 
wear and the programming overhead of performing MOTOR ON and MOTOR 
OFF operations.) You must, however, ensure that all accesses have been completed 
before performing a MOTOR OFF. This entails making certain all opened files on 
that drive or drive pair have been closed (which implies that all READs, WRITEs, 
and SEEKs have been completed), and that responses have been received from DFS 
for all requests to the DELETE, RENAME, ATTRIB, FORMAT, LOAD, and 
DISKIO services. 



An attempt to access a file on a mini-size drive with the motor off will result in a 
"Not Ready" I/O error (see "Error Codes" later in this chapter). 

Setting Sector Mode for Hard Disk 

Each drive connected to an iSBC 206 controller can be set for either 128 bytes per 
sector or 512 bytes per sector. The selection of a mode is accomplished for each drive 
via a switch on the controller board . Make certain, if you have hard disk units, that the 
switches are properly set. 

Requests for DFS Services 

To request any DFS service, the user task must perform the following operations: 

• build a message which describes the request. 

• send (RQSEND) the message to the appropriate exchange. 

• wait (RQWAIT) for the request to be processed. 

• check for errors. 

Instructions for coding these operations are given in this section. Each DFS service is 
covered separately; request message format and rules are provided along with ex- 
amples of usage. Several things should be noted about the examples: 

• The examples are intended to be succinct illustrations of the essential use of 
each service; they should not be construed as complete, executable user tasks. 

• In order to make the usage of the services as clear as possible, the examples 
have been coded in PL/M. The OPEN example, however, has also been coded 
in assembly language to show the corresponding constructs. There is a high 
degree of commonality among the user interfaces to the various DFS services, 
and it should be easy for assembly-language programmers to "translate" the 
other examples as necessary. 
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• Each example includes an error routine that is empty except for a comment 
which states that user code should replace the comment. This approach has 
been taken in order to emphasize that user tasks must be prepared for errors, 
but that the technique used for error processing is necessarily application- 
dependent. 

• Comments show the values that variables (primarily message fields) are 
expected to contain. In ROM-based applications these values must be moved 
from ROM constants when the user task is initialized (see "Planning Memory 
Space" in Chapter 2). RAM areas cannot be initialized in the RMX/80 en- 
vironment with the PL/M INITIAL or assembly language DB/DW directives 
unless the data is loaded from an external device. 

• User buffer areas may be made controller-addressable or not, depending on 
several factors which are discussed in the "Defining System Components" sec- 
tion later in this chapter. The examples show how to code both types of buf- 
fers. 

• The examples show user-coded DFS message formats. PL/M users may 
include the file DFSMSG.ELT in their programs; this file contains standard 
declarations of all DFS messages. 

LENGTH and MARKER. LENGTH and MARKER are two conceptual entities 
which are referred to often in the remainder of this chapter. LENGTH is the number 
of bytes which a file currently contains. Elach byte in the file is numbered; the first 
byte is byte number 0. MARKER is an indication of a task's current position in a file 
in terms of byte number. READ and WRITE operations transfer data starting at 
MARKER. If the value of MARKER is 105 and a READ is issued, the first byte 
transferred to the user task is byte number 105 (the 106th byte in the file). User tasks 
do not have direct access to the values of LENGTH and MARKER, but these values 
can easily be calculated when needed by means of the SEEK service. Each task/file 
combination has its own MARKER; it is not affected by the activities of other tasks 
that may be reading the same file so long as each task has separately opened the file 
(i.e., the tasks access the file through different active file request exchanges). 
LENGTH is not changed by READ operations. If separate tasks are reading the 
same file through a common exchange (not recommended), both tasks can change 
MARKER, and precautions must be taken to prevent the tasks from interfering with 
each other. 

File Name Block. Several services (OPEN, ATTRIB, RENAME, DELETE, FOR- 
MAT, and LOAD) require one or more file names to be associated with a request for 
service. These file names are supplied by the user in File Name Blocks, or FNB's. 
FNB's are generally declared in the task that opens the file, although they may be 
declared anywhere that is convenient. A field called FILEPTR in the requesting 
message contains the address of the associated FNB. 



Format. The format of the File Name Block is shown in Figure 7-5. 



DEVICENAME 



EXTENSION 



Figure 7-5 . File Name Block 
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DEVICENAME must be two alphanumeric ASCII characters (excluding lower-case 
letters) specifying the device upon which the file resides. 

FILENAME must be one to six alphanumeric ASCII characters (excluding lower- 
case letters) specif ying the name of the file. Blanks are not permitted. The characters 
must be left-justified and any unused positions to the right filled with ASCII nulls 
(binary zeros). 

EXTENSION must be zero to three alphanumeric ASCII characters (excluding 
lower-case letters) specifying the extension appended to the file name. Blanks are not 
permitted. The characters must be left-justified and any unused positions filled with 
ASCII nulls (binary zeros). 

Notes. If the FNB is placed in RAM, the user task must move ROM-based con- 
stants to it when the task is initialized by the Nucleus, or load the values from an ex- 
ternal device. PL/M users can INCLUDE, the file FNB.ELT in their programs to ob- 
tain a standard FNB declaration. 

Examples. The examples show sample coding for two File Name Blocks. The first 
file resides on device Fl, is named CONTRL and has the extension TXT (in ISIS-II 
the file would be known as :Fl:CONTRL.TXT). The second file is called ZAP1 and 
resides on unit F2. Note that the unused portions of the FILENAME and EXTEN- 
SION fields are filled with binary zeros. Note also that both FNB's are built in 
ROM; this is the recommended approach unless FNB fields are to be updated by 
user tasks. 



/*"* FILE NAME BLOCK EXAMPLES (PL/M) **"/ 

DECLARE FNB$1(11) BYTE DATA ('F1CONTRLTXT'); 

DECLARE FNB$2(11) BYTE DATA ('F2ZAPr,0,0,0,0,0); 

; FILE NAME BLOCK EXAMPLES (ASSEMBLY LANGUAGE) 



OPEN Request. The OPEN service connects a user task and a disk file. The con- 
nection is an exchange to which subsequent requests for I/O are directed. So long as 
memory is available, a task may open an unlimited number of files. The same file 
may be opened for read-only access by any number of tasks. When a new file is 
opened for output or update, its attribute bits are reset to zero (see ATTRIB request); 
the file then cannot be accessed by another task until it is closed, then opened again 
by the other task. 

If a task attempts to READ, WRITE, SEEK or CLOSE a file that is not open to it, 
the result is unpredictable and can be fatal to the system. 

Conflicts can arise in a multitasking environment when more than one task attempts 
access to the same file. Table 7-2 shows DFS' response when OPEN requests are 
made under different circumstances. If the open is allowed, the values which 
LENGTH and MARKER assume are shown; if the operation is disallowed, the error 
code which is returned in STATUS is shown. "L=current" means that LENGTH is 
set to the current length of the file. 

Applications using the OPEN service must be configured to include RMX/80 tasks 
named DIRSVC and DISKIO. (See, in this chapter, the section named Defining 
System Components.) 



FNB1 
FNB2 



CSEG 

DB 

DB 



•F1CONTRLTXT' 
'F2ZAP1 ',0,0,0,0,0 
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Table 7-2. Responses oi : DFS to OPEN Requests 



FILE CONDITION AT 
TIME OF REQUEST 


ACCESS REQUESTED 


READ 


WRITE 


UPDATE 


Does Not Exist 


STATUS=13 


L=0* 
M=0 


L=0* 
M=0 


Exists 

Closed 


L=current 
M=0 


L=0** 
M=0 


L=current 
M=0 


Open For Read 


L=current 
M=0 


STATUS=12 


STATUS=12 


Open For Write 


STATUS=12 


STATUS=12 


STATUS=12 


Open For Update 


STATUS=12 


STATUS=12 


STATUS=12 



"Note that the file is created. 



"Note that if an existing file is opened for output (WRITE), the file is deleted and re- 
created empty — any data in the file is lost. 

Request Message. The OPEN request message must be sent to the RQOPNX ex- 
change. 

The format of the OPEN message is shown in figure 7-6. Asterisks denote fields that 
must be coded by the user task before the message is sent. Shaded fields are those set 
or changed by DFS when it returns the message. 



LENGTH is 17. 

TYPE is DFSSOPN (15). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. In order to avoid mismat- 
ching tasks and messages, a separate response exchange should generally be 
dedicated to each task/file combination. 






LINK 


2 


LENGTH" 


4 


TYPE- 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE" 


9 


STATUS 


11 


FILEPTR* 


13 


ACCESS* 


15 


AFR EXCHANGE 



Figure 7-6. OPEN Request Message 
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When DFS returns this message, it sets STATUS to indicate the results of the OPEN 
request. Zero is returned if the file is opened successfully; for details on nonzero 
values of STATUS, refer to the "Error Codes" section later in this chapter. The 
user must check the contents of STATUS to be sure the file has been opened suc- 
cessfully before attempting I/O operations on the file. 

FILEPTR must contain the address of the File Name Block which specifies the file 
to be opened. 

ACCESS must specify one of the following codes: RDSACC (1), WRTSACC (2), or 
UPDSACC (3). RDSACC indicates that the file is to be opened for input (reading); 
WRTSACC, output (writing); and UPDSACC, update (both reading and writing). 
PL/M users may INCLUDE the file OPNACC.ELT in their programs to define the 
symbolic values for these codes. 

When DFS returns the message, it sets AFR XCH to the address of the Active File 
Request Exchange that it builds if the file is opened successfully. All READ, WRITE, 
SEEK, and CLOSE request messages for this task-file combination must be sent to 
this exchange. If the OPEN is unsuccessful (STATUS ^0), the contents of this field 
are undefined and should not be accessed by the user task. 



Examples. The coding examples open the files defined previously in the File Name 
Block section: CONTRL.TXT is opened for input (reading) and ZAP1 is opened for 
output (writing). Message fields that need not be coded by the user are initialized to 
zero for convenience; this is not required, however. 



/•*** "OPEN" EXAMPLE (PL/M) ' 



*/ 



/* OPEN MESSAGES */ 

DECLARE (OPEN$CONTRL$MSG,OPEN$ZAP1$MSG) STRUCTURE 
(LINK ADDRESS, 
LENGTH ADDRESS, 
TYPE BYTE, 
HOMESEXCHANGE ADDRESS, 
RESPONSE SEXCHANGE ADDRESS, 
STATUS ADDRESS, 
FILEPTR ADDRESS, 
ACCESS ADDRESS, 
AFR$XCH ADDRESS); 
/* ASSUMED CONTENT OF MESSAGES : */ 

/* 0,17, DFS$OPN,0, .CONTRL$RESPONSE,0, .FNB1, RDSACC, */ 
/* 0, 17, DFSSOPN, 0, .ZAP1SRESPONSE, 0, .FNB2, WRTSACC, */ 

/* OPEN AND RESPONSE EXCHANGES */ 

DECLARE RQOPNX EXCHANGESDESCRIPTOR EXTERNAL; 

DECLARE (CONTROLSRESPONSE, 

ZAP1SRESPONSE) EXCHANGESDESCRIPTOR; 



DECLARE (T1,ERROR$CODE) 



ADDRESS; /* FOR RQWAIT, ERROR ROUTINE */ 



OPENSERROR: PROCEDURE(X); 

DECLARE X ADDRESS; 

/* USER CODE TO HANDLE ERRORS GOES HERE ' / 

END OPENSERROR; 
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/* BUILD RESPONSE EXCHANGES */ 
CALL RQCXCH(.CONTRL$RESPONSE); 
CALL RQCXCH(.ZAP1$RESPONSE); 



/"OPEN FILES*/ 

CALL RQSEND(. RQOPNX,. OPEN$CONTF!L$MSG); 
CALLRQSEND(.RQOPNX,.OPEN$ZAP1$MSG); 

/* WAIT UNTIL BOTH OPENS ARE EXECUTED */ 
T1 = RQWAIT(.CONTRL$RESPONSE, 0); 
T1 = RQWAIT(.ZAP1$RESPONSE, 0); 

/* CHECK FOR ERRORS */ 

IF (ERROR$CODE:=OPEN$CONTRL$MSG.STATUS)<> THEN 

CALL OPEN$ERROR(ERROR$CODE); 
IF(ERROR$CODE:=OPEN$ZAP1$MSG.STATUS)OOTHEN 

CALL OPEN$ERROR(ERROR$CODE); 



;"OPEN" EXAMPLE (ASSEMBLY LANGUAGE) 
; CSEG 

EXTRN RQOPNX ;OPEN EXCHANGE - DEFINED IN CONFIG. MOD. 

;BUILD RESPONSE EXCHANGES 



LXI 


B.CWAITX 


ADDR WHERE EXCH IS TO BE BUILT 


CALL 


RQCXCH 


BUILD IT 


LXI 


B.ZWAITX 


ADDR WHERE EXCH IS TO BE BUILT 


CALL 


RQCXCH 


BUILD IT 


;OPEN FILES 






LXI 


B, RQOPNX 


ADDRESS OF OPEN EXCHANGE 


LXI 


D.CNTMSG 


MESSAGE DESCRIBING 'CNTL' FILE 


CALL 


RQSEND 


SENDTHEOPEN MESSAGE 


LXI 


B, RQOPNX 


ADDRESS OF OPEN EXCHANGE 


LXI 


D.ZAPMSG 


MESSAGE DESCRIBING 'ZAPV FILE 


CALL 


RQSEND 


SEND THE OPEN MESSAGE 



;WAIT UNTIL BOTH OPENS ARE EXECUTED 



LXI 


B.CWAITX 


WHERE WE WANT TO WAIT 


LXI- 


D,0 


NO TIME LIMIT 


CALL 


RQWAIT 


WAIT 


LXI 


B.ZWAITX 


WHERE WE WANT TO WAIT 


LXI 


D.O 


NO TIME LIMIT 


CALL 


RQWAIT 


WAIT 



;CHECK FOR ERRORS 



CKCNT 


EQU 


$ 




NOERR 


EQU 









LDA 


CSTAT 


;LOW BYTE OF STATUS 




CPI 


NOERR 


;IS IT ZERO? 




JZ 


CKZAP 


;YES, CONTINUE 




LXI 


B, CSTAT 


;NO, PASS STATUS TO ERROR RTN 




CALL 


OPNERR 


;TAKE CARE OF THE ERROR 


CKZAP 


EQU 


$ 






LDA 


ZSTAT 


;LOW BYTE OF STATUS 




CPI 


NOERR 


;IS IT ZERO? 




JZ 


CONTIN 


;YES, FILE OPENED, CONTINUE 




LXI 


B, CSTAT 


;NO, PASS STATUS TO ERROR RTN 




CALL 


OPNERR 


;TAKE CARE OF ERROR 




JMP 


CONTIN 


;GO AROUND ERROR RTN 


OPNERR EQU 


$ 


;ERROR ROUTINE 



;USER CODE TO HANDLE ERRORS GOES HERE 
RET 



CONTIN EQU $ 
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;OPEN MESSAGE FOR 'CNTL' FILE 



CNTMSG 

CLINK 

CLEN 

CTYPE 

CHOMEX 

CRESPX 

CSTAT 

CFILEP 

CACCES 

CAFRX 



DS 17 

EQU CNTMSG 
EQU CNTMSG+2 
EQU CNTMSG+4 
EQU CNTMSG+5 
EQU CNTMSG+7 
EQU CNTMSG+9 
EQUCNTMSG+11 
EQUCNTMSG+13 
EQUCNTMSG+15 



VALUES MOVED FROM ROM: 


17 

15 (OPEN) 


ADDR (CWAITX) 


ADDR (FNB1) 
1 (READ) 




;OPEN MESSAGE FOR 'ZAP1' FILE 



ZAPMSG 

ZLINK 

ZLEN 

ZTYPE 

ZHOMEX 

ZRESPX 

ZSTAT 

ZFILEP 

ZACCES 

ZAFRX 



DS 17 

EQU ZAPMSG 

EQU ZAPMSG+2 

EQUZAPMSG+4 

EQUZAPMSG+5 

EQUZAPMSG+7 

EQU ZAPMSG+9 

EQUZAPMSG+11 

EQUZAPMSG+13 

EQUZAPMSG+15 



VALUES MOVED FROM ROM: 


17 

15(OPEN) 


ADDR (ZWAITX) 


ADDR (FNB2) 
2 (WRITE) 




;LOCAL EXCHANGES 
CWAITX DS 10 
ZWAITX DS 10 



; RESPONSE EXCHANGE FOR 'CONTRL' 
; RESPONSE EXCHANGE FOR 'ZAP1 ' 



READ Request. The READ service transfers data from an open disk file to a user 
task. The file must be open for input or update. Successive reads to the same file are 
processed serially in the order in which the requests are made (FIFO). The data 
transfer begins with the byte at location MARKER and continues until the number 
of bytes requested by the user has been read or the end of the file is reached, 
whichever occurs first. 

Applications using the READ service must be configured to include RMX/80 tasks 
named DIRSVC and DISKIO. (See, in this chapter, the section named Defining 
System Components.) 

Request Message. The READ request message must be sent to the exchange 
established by DFS when the file was opened. 

The format of the READ message is shown in figure 7-7. Asterisks denote fields that 
must be coded by the user task before the message is sent. Shaded fields are those set 
or changed by DFS when it returns the message. 






LINK 


2 


LENGTH- 


4 


TYPE* 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE* 


9 


STATUS 


11 


BUFFER- 


13 


COUNT* 


15 


ACTUAL 



Figure 7-7. READ Request Message 
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LENGTH is 17. 

TYPE is DFSSRD (8). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify th e address of the user-defined exchange at 
which the requesting task waits for a response from DFS. Although there is no pro- 
hibition against setting up a new exchange at which to wait for reads, the straight- 
forward approach is to use the same exchange at which the task waited for the file to 
be opened. No other task should use this exchange. 

When DFS returns this message, it sets STATUS to indicate the result of the READ 
request. Zero is returned if the data is rsad successfully; for details on nonzero 
values of STATUS, refer to the "Error Codes" section. The user task should check 
STATUS after every READ to ensure that the operation has completed normally. 

BUFFER must specify the address of the beginning of the memory area where DFS 
is to place the requested data. If the buffer is located in the controller-addressable 
memory module, data can, in some cases, be placed in the buffer by DMA, resulting 
in a substantial performance improvement. (See "Defining System Components" 
later in this chapter.) You must ensure that the buffer is large enough to hold the 
amount of data requested in the COUNT field. If the buffer is short, the adjacent 
data in memory will be overwritten without indication to the user. 

COUNT must specify the number of bytes to be read from the file. If COUNT = 0, 
the request is processed normally, but no data is read. 

When DFS returns this message, it sets ACTUAL to the actual number of bytes read 
into the user buffer. MARKER is incremented by ACTUAL during each read. AC- 
TUAL can be greater than zero but less than COUNT in two cases: if an I/O error 
occurs, or if end-of-file is encountered before the requested number of bytes has 
been transmitted. The condition (STATUS = and ACTUAL = 0) signals that the 
user is at end-of-file (unless COUNT = 0). Your task should therefore check the con- 
tents of ACTUAL as well as STATUS after every read. DFS will continue to return 
ACTUAL = if you try to read past the end of the file. If ACTUAL is less than 
COUNT, the data in the user buffer which is beyond ACTUAL should be con- 
sidered undefined. 



Example. In the coding example, the CONTRL.TXT file used in the File Name 
Block and OPEN examples is read sequentially from beginning to end. A few 
variables and other identifiers are used which were defined in the previous 
examples. Fields in the READ message that the user is not required to code are 
initialized to zero, although this is not strictly necessary. The user buffer is controller- 
addressable; consequently, READSBUF below is declared EXTERNAL, in order to 
match the PUBLIC declaration of it in the controller-addressable memory module 
(see the configuration portion of this chapter.) 



/**** "READ" EXAMPLE (PL/M) "**/ 

DECLARE READ$CONTRL$MSG STRUCTURE! 

LINK ADDRESS, 

LENGTH ADDRESS, 

TYPE BYTE, 

HOMESEXCHANGE ADDRESS 

RESPONSESEXCHANGE ADDRESS, 

STATUS ADDRESS, 

BUFFER ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS); 
/* ASSUMED VALUES: */ 

/* 0,17, DFSSRD, 0, .CONTRLSRESPONSE, , .READSBUF, 256, * / 
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/* BUFFER FOR DATA DEFINED IN C.A.M. MODULE */ 
DECLARE READSBUF (256) BYTE EXTERNAL; 



/* END-OF-FILE CONTROLS */ 
DECLARE MORESDATA 
DECLARE TRUE 
DECLARE FALSE 



BYTE; 

LITERALLY 'OFFH'; 
LITERALLY '00H' ; 



/* ADDRESS OF AFR$EXCHANGE RETURNED BY OPEN */ 
DECLARE READSEXCHANGE ADDRESS; 



/* ROUTINE TO HANDLE ERRORS*/ 
READSERROR: PROCEDURE(X); 
DECLARE X 



ADDRESS; 



/* USER ERROR PROCESSING CODE GOES HERE */ 
END READSERROR; 

/•ASSUME FILE IS OPEN */ 

/* SET EOF CONTROL AND ADDRESS OF READ EXCHANGE */ 
MORESDATA = TRUE; 

READSEXCHANGE = OPENSCONTRLSMSG.AFRSEXCHANGE; 

/* START READING */ 
DO WHILE MORESDATA; 

CALL RQSEND(READ$EXCHANGE, READ$CONTROL$MSG); 

/* WAIT FOR READ TO COMPLETE */ 
T1 = RQWAIT(.CONTRL$ RESPONSES) ; 

/"CHECK FOR ERRORS*/ 

IF(ERROR$CODE:=READ$CONTRL$MSG.STATUS)<>0 
THEN CALL READSERROR(ERRORSCODE); 

/•CHECK FOR ENDOF FILES */ 

IF READ$CONTRL$MSG.ACTUAL>0 THEN DO; 

/•CODE TO PROCESS DATA GOES HERE*/ - 

END; 

ELSE MORESDATA = FALSE; /* STOP READING */ 



WRITE Request. The WRITE service transfers data from user task memory to an 
open file. The file must be open for output or update. Successive WRITE requests to 
the same file are processed serially in the order the requests are made. Intermixed 
READ and WRITE requests to the same file are also processed serially. Data is writ- 
ten on the file starting at location MARKER and continues until the number of bytes 
requested by the user is transferred. 

Applications using the WRITE service must be configured to include RMX/80 tasks 
named DIRSVC and DISKIO. (See, in this chapter, the section named Defining 
System Components.) 

Request Message. The WRITE request message must be sent to the exchange 
established by DFS when the file was opened. 

The format of the WRITE message is shown in figure 7-8. Asterisks denote fields 
that must be coded by the user task before the message is sent. Shaded fields are 
those set or changed by DFS when it returns the message. 



END; 
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LINK 


2 


LENGTH- 


A 


TYPE- 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE* 


9 


SI/ I US 


11 


BUFFER* 


13 


COUNT* 


15 





Figure 7-8. WRITE Request Message 



LENGTH is 17. 

TYPE is DFS$WRT(12). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. Although there is no pro- 
hibition against setting up a new exchange at which to wait for writes, the straight- 
forward approach is to use the same exchange at which the task waited for the file to 
be opened. No other task should use this exchange. 

When DFS returns this message, it sets STATUS to indicate the result of the WRITE 
request. Zero is returned if the data is written successfully; for details on nonzero 
values of STATUS, refer to the "Error Codes" section. The user task should check 
STATUS after every WRITE to ensure that the operation has completed normally. 

BUFFER must specify the address of the beginning of the memory area from which 
DFS is to write the data. If the buffer is located in the controller-addressable 
memory module, data can, in some cases, be written from the buffer by DMA, 
resulting in a substantial performance improvement. (See "Defining System Com- 
ponents" later in this chapter.) 

COUNT must specify the number of bytes to be transferred from BUFFER to the 
file. It is the user's responsibility to ensure that COUNT does not exceed the length 
of the buffer; if it does, whatever data lies beyond the buffer will be written to the 
disk without indication to the user. If COUNT = 0, the request is processed normal- 
ly, but no data is written. 

When DFS returns this message, it sets ACTUAL to the actual number of bytes writ- 
ten to the disk. MARKER is incremented by ACTUAL during the write operation. 
If the write extends the file, LENGTH is also incremented to the new length of the 
file. If ACTUAL is less than COUNT, an error has occurred. (STATUS identifies 
the error.) 

Example. In the coding example, the file ZAP1 which was used in the File Name 
Block and OPEN examples is created with ten 80-byte records. Note that if there is 
already a file called ZAP1 on the disk, its contents are lost. The user buffer is not 
controller-addressable and is therefore declared and allocated in the module (i.e., it 
is not declared EXTERNAL). 
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/ WRITE" EXAMPLE (PL/M) *"**/ 
/* DEFINE WRITE MESSAGE */ 

DECLARE WRITE$ZAP1$MSG STRUCTURE( 

LINK ADDRESS, 

LENGTH ADDRESS, 

TYPE BYTE, 

HOMESEXCHANGE ADDRESS, 

RESPONSESEXCHANGE ADDRESS, 

STATUS ADDRESS, 

BUFFER ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS); 
/* ASSUMED VALUES: */ 



/* 



0, 17, DFSSWRT, 0, .ZAP1SRESPONSE, , .WRITE$BUF, 80, /* 



DECLARE WRITE$BUF(80) BYTE, /* 

ZAP1$EXCHANGE ADDRESS, /* 

I BYTE, /* 

T1 ADDRESS, /* 
ERRORSCODE ADDRESS; 



FOR DATA - NO DMA TRANSFER * / 
FILE EXCHANGE*/ 
LOOP CONTROL*/ 
FOR RQWAIT */ 



/* HANDLE ANY ERRORS*/ 
WRITE$ERROR: PROCEDURE(X); 

DECLARE X ADDRESS; 

/* USER ERROR HANDLING CODE GOES HERE /* 
END WRITESERROR; 

/* ASSUME ZAP1 IS OPEN */ 

/* GET EXCHANGE ADDRESS OF ZAP1 '/ 

ZAP1SEXCHANGE - OPEN$ZAP1$MSG.AFR$EXCHANGE; 

/* BUILD THE FILE*/ 
DO 1 = 1 T0 10; 

/* CODE TO BUILD RECORD IN WRITESBUF GOES HERE */ 
/* WRITE THE BUFFER*/ 

CALL RQSEND(ZAP1$EXCHANGE,.WRITE$ZAP1$MSG); 

/* WAIT FOR COMPLETION */ 

T1 = RQWAIT(.ZAP1$RESPONSE,0); 



/'CHECK FOR ERRORS*/ 

IF (ERROR$CODE:=WRITE$ZAP$MSG.STATUS) <> 
THEN CALL WRITE$ERROR(ERROR$CODE); 



END; 



SEEK Request. The SEEK service gives the user access to the MARKER value 
associated with an open file. The user may obtain the current value of MARKER or 
set it to a new value. Since data transfers use MARKER as a starting point, SEEK 
enables the user to perform direct (or "random") access file processing. Note that 
SEEK does not transfer data: it merely returns the value of MARKER or sets it to a 
new value in preparation for subsequent reads and/or writes. Intermixed SEEKs, 
READs, and WRITEs to the same file are processed serially in the order in which 
they are requested. SEEK can also be used to extend the LENGTH of a file if the file 
is open for update. 
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Some knowledge of the DFS file structure is necessary to use SEEK. While Appen- 
dix E contains a complete description of the file structure, the following treatment 
should suffice for most users. 

DFS files are physically organized into blocks of 128 bytes (the length of a disk sec- 
tor). A standard-size single-density diskette has 1915 of these blocks available for 
user data. (Some disk space is used by the system for the diskette directory and other 
system data.) The maximum length of one user file residing on a standard single- 
density diskette, then, is 1915 x 128 = 245,120 bytes. Standard-size double-density 
diskettes contain 3,826 blocks or 489,788 bytes; mini-size diskettes, 590 blocks or 
75,520 bytes; hard disks, 28,024 blocks or 3,587,072 bytes. Note that these maximum 
figures hold only when there is a single file on the disk; as files are added, additional 
space is used by the system to keep track of the files, reducing the space available for 
user data. (See Appendix E for details.) The first block of a file is block number 0; the 
first byte in a block is byte number 0. 

The user controls MARKER with the BLOCKNO (block number) and BYTENO 
(byte number) fields in the SEEK message. At any time a file is open, MARKER can 
be expressed in terms of BLOCKNO and BYTENO as follows: 

MARKER = ((BLOCKNO x 128) + BYTENO) (modulo 2 23 ) 



The (modulo 2 23 ) term in the equation does not affect the computation of MARKER 
unless ((BLOCKNO X 128) + BYTENO) >8,388,608 — an illegal value for disk 
files. Therefore in practice the term can be ignored for disks. Notice also that for files 
that are less than 65,536 bytes in length, BLOCKNO can be set to zero, making 
MARKER simply equal to BYTENO. For example, in a file 10,000 bytes long, 
MARKER could be set to 1289 by specifing either of the following: 



However, DFS always sets as high as possible the value of BLOCKNO which it 
returns to the user. For example, if the user sets MARKER as BLOCKNO = 2, 
BYTENO = 128 and then requests the current value of MARKER, DFS returns 
BLOCKNO = 3, BYTENO = 0. 

SEEK operates in any of five user-specified modes: 
CUR: Return the current value of MARKER. 

INCR: Increment MARKER by a specified value (move relatively forward in the file). 
DECR: Decrement MARKER by a specif ied value (move relatively backward in the file). 
SET: Set MARKER to a specified value (move to an absolute location in the file). 

EOF: Set MARKER to LENGTH and return its value (move to end-of-f ile) . 

Table 7-3 illustrates a sequence of legal SEEK requests in a file which is assumed to 
contain 8692 bytes. 



BLOCKNO = 10 
BYTENO = 9 



or 



BLOCKNO = 
BYTENO = 1289 
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Table 7-3 . Responses of DFS to a Sample Sequence of SEEK Requests 

(8692-byte file) 



Values at Time of Request 


Values Following Request 


MARKER 


MODE 


BLOCKNO 


BYTENO 


STATUS 


MARKER 


BLOCKNO 


BYTENO 





CUR 





















INCR 


10 


8 





1288 


10 


8 


1288 


DECR 





4 





1284 


10 


4 


1284 


SET 


22 


5 





2821 


22 


5 


2821 


EOF 









8692 


67 


116 



The following additional rules apply to SEEK requests: 

• The file must be open for input or update. 

• Decrementing MARKER past the beginning of the file is not permitted. (An 
error code will be returned in STATUS.) 

• If the file is open for input, attempting to move MARKER beyond the end of 
the file by SKSSET or SKSINCR is not permitted. (An error code will be 
returned.) 

• If the file is open for update, it can be extended with SKSSET or SKSINCR. 
This causes LENGTH to be increased. Disk space is not actually allocated for 
user data, however, until data is written into the extended area. Space for 
pointer blocks, however, is allocated (see Appendix E). When a read is done 
on one of these unallocated data areas, ASCII nulls (binary zeros) are placed 
in the user's buffer. 



Request Message. The SEEK request message must be sent to the active file request 
exchange established by DFS when the file was opened. 

The format of the SEEK message is shown in figure 7-9. Asterisks denote fields that 
must be coded by the user task before the message is sent. Shaded fields are those set 
or changed by DFS when it returns the message. 



LENGTH is 17. 

TYPE is DFS$SK(13). 

HOME EXCHANGE is not used by DFS. 






L NK 


2 


LENGTH* 


4 


TYPE- 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE* 


9 


STf TUS 


11 


MODE* 


13 


BLOOKNO* 


15 


BYTENO* 



Figure 7-9. SEEK Request Message 
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RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. the simplest technique is 
to use the same exchange at which the task waited for the file to be opened. No other 
task should use this exchange. 

When DFS returns this message, it sets STATUS to indicate the result of the SEEK 
request. Zero is returned if the request is processed successfully; for details on 
nonzero values of STATUS, refer to the "Error Codes" section. The user task 
should check STATUS after every SEEK o ensure that the operation has completed 
normally. 

MODE must specify one of the following codes: SK$CUR (0), SK$DECR (1), 
SK$SET (2), SK$INCR (3), or SK$EOF (4). These codes are defined earlier in this 
section on the SEEK request. PL/M users may INCLUDE the file SEEK.ELT in 
their programs to define the symbolic values for these codes. 

The significance of BLOCKNO depends on the mode specified. If MODE is 
SKSDECR, SKSSET, or SKSINCR, the BLOCKNO field must specify the block 
number portion of the MARKER calculation, and DFS does not change this field 
when it returns the message. If MODE is SK$CUR or SKSEOF, no user coding is re- 
quired; DFS returns the appropriate value in this field. 

The significance of BYTENO depends on the mode specified. If MODE is 
SKSDECR, SKSSET, or SKSINCR, the BYTENO field must specify the byte 
number portion of the MARKER calculation, and DFS does not change this field 
when it returns the message. If MODE is SKSCUR or SKSEOF, no user coding is re- 
quired; DFS returns the appropriate value in this field. 



Example. As an example of using SEEK, assume a file named EXPMNT contains a 
100-byte record for each of 40 experiments which are being monitored. Each record 
begins with an eight-bit temperature field which must be updated periodically. The 
program shown in the coding example accepts an experiment number (1-40) and a 
temperature value and updates the corresponding disk record. The entire record is 
read, although this is not strictly necessary in this case since only the first byte is up- 
dated. The user buffer is not controller-addressable. 



/***« "SEEK" EXAMPLE (PL/M) *•*•/ 

UPDATESTEMP: PROCEDURE(EXPERIMENT,NEW$TEMP); 
DECLARE (EXPERIMENT, NEW$TEMP) BYTE; 

/* DEFINE SEEK MESSAGE USING SET MODE */ 



DECLARE SEEKSMSG STRUCTURE( 

LINK ADDRESS, 

LENGTH ADDRESS, 

TYPE BYTE, 

HOMESEXCHANGE ADDRESS, 

RESPONSESEXCHANGE ADDRESS, 

STATUS ADDRESS, 

MODE ADDRESS, 

BLOCKNO ADDRESS, 

BYTENO ADDRESS); 
/* ASSUMED VALUES: */ 

/* 0, 17, DFSSSK, 0, .WAITSEXCH, 0, SKSSET, 0,0 */ 
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/* RECORD AREA: BUFFER(O) CONTAINS TEMP; DMA TRANSFERS NOT POSSIBLE*/ 
DECLARE BUFFERO00) BYTE; 

/* VARIABLE FOR ADDRESS RETURNED BY RQWAIT */ 
DECLARE T1 ADDRESS; 

/* ASSUME: 

* EXPMNT HAS BEEN OPENED FOR UPDATE, 

* READ$MSG AND WRITESMSG HAVE BEEN DECLARED, 

* AFRSEXCHANGE FOR EXPMNT IS EXPMNT$EXCH, 

* TASK WILL WAIT FOR I/O AT WAIT$EXCH. 
*/ 

/* TAKE CARE OF ERRORS * / 
ERRORSHANDLER: PROCEDURE(X); 
DECLARE X ADDRESS; 

/* USER CODE TO PROCESS ERRORS GOES HERE */ 
END ERRORSHANDLER; 

/* COMPUTE MARKER VALUE -NOTE THAT BLOCKNO IS NOT USED */ 
SEEKSMSG.BYTENO = (EXPERIMENT - 1) * 100; 
SEEKSMSG. BLOCKNO = 0; 

/* ISSUE SEEK*/ 

CALL RQSEND(EXPMNT$EXCH,.SEEK$MSG); 
T1 = RQWAIT(.WAIT$EXCH, 0); 
IF SEEKSMSG. STATUS <> THEN 

CALL ERROR$HANDLER(.SEEK$MSG); 

/* READ RECORD INTO BUFFER — NOTE THAT MARKER IS ADVANCED */ 
CALL RQSEND(EXPMNT$EXCH,.READ$MSG); 
T1 = RQWAIT(.WAIT$EXCH, 0); 
IF READSMSG. STATUS <> THEN 

CALL ERROR$HANDLER(. READSMSG); 

/* UPDATE THE RECORD * / 
BUFFER(O) = NEWSTEMP; 

/* RESET MARKER */ 

SEEKSMSG.MODE = SKSDECR; 

SEEKSMSG. BLOCKNO = 0; 

SEEKSMSG.BYTENO = 100; 

CALL RQSEND(EXPMNT$EXCH,. SEEKSMSG); 

T1 = RQWAIT(.WAIT$EXCH, 0); 

IF SEEKSMSG. STATUS <> THEN 

CALL ERRORSH AN DLER(. SEEKSMSG); 
SEEKSMSG.MODE = SKSSET; 

/* REWRITE RECORD FROM BUFFER */ 

CALL RQSEND(EXPMNT$EXCH.,WRITE$MSG); 

T1 = RQWAIT(.WAITSEXCH.O); 

IF WRITESMSG.STATUS <> THEN 

CALL ERROR$HANDLER(. WRITESMSG); 

END UPDATESTEMP; 




7-22 



RMX/80 



Disk File System 



CLOSE Request. The CLOSE service disconnects a user task from an open disk 
file. Other tasks reading the same file are not affected so long as the tasks have 
separately opened the file. DFS processes any outstanding I/O requests before clos- 
ing the file. When the file is closed, the memory used by DFS to process I/O requests 
is released, and the exchange which was created when the file was opened is 
destroyed. If messages are sent to this exchange after the file is closed, the results are 
unpredictable and may be fatal to the system. 

Applications using the CLOSE service must be configured to include RMX/80 tasks 
named DIRSVC and DISKIO. (See, in this chapter, the section named Defining 
System Components.) 

Request Message. The CLOSE request message must be sent to the exchange 
established by DFS when the file was opened. 

The format of the CLOSE message is shown in figure 7-10. Asterisks denote fields 
that must be coded by the user task before the message is sent. Shaded fields are 
those set or changed by DFS when it returns the message. 



HOME EXCHANGE 



RESPONSE EXCHANGE- 
STATUS 



Figure 7-10. CLOSE Request Message 



LENGTH is 11. 

TYPE is DFS$CLS(14). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. The simplest technique is 
to use the same exchange at which the task waited for the file to be opened. No other 
task should use this exchange. 

When DFS returns this message, it sets STATUS to indicate the result of the CLOSE 
request. Zero is returned if the request is processed successfully; for details on 
nonzero values of STATUS, refer to the "Error Codes" section. The user task 
should check STATUS after performing the CLOSE to ensure that the operation has 
completed normally. 

Example. The following listing provides sample coding of a CLOSE request. This 
example refers to the coding example given for the OPEN service. 



/**" "CLOSE" EXAMPLE (PL/M) *»**/ 
/* ASSUME: 

FILE NAMED SAMPLE IS OPEN, 

OPEN MESSAGE IS OPENSMSG , 

WAIT EXCHANGE IS REPLYSEXCH, 

FILE'S AFR EXCHANGE IS SAMPLE$EXCH. 
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*/ 

/* FOR ADDRESS RETURNED FROM RQWAIT * / 
DECLARE T1 ADDRESS; 



/* TAKE CARE OF ANY ERRORS */ 
CLOSE$ERR: PROCEDURE(X); 

DECLARE X ADDRESS; 

I* USER ERROR ROUTINE GOES HERE * / 

END CLOSESERR; 



/* CHANGE OPEN MESSAGE TO CLOSE * / 
OPENSMSG. LENGTH = 11; 
OPENSMSG.TYPE - DFSSCLS; 



/'CLOSE THE FILE*/ 

CALL RQSEND(SAMPLE$EXCH,.OPE!M$MSG); 
T1 = RQWAIT(.REPLY$EXCH,0); 
IF OPENSMSG.STATUS <> OTHEN 

CALL CLOSE$ERR(OPEN$MSG. STATUS); 



DELETE Request. The DELETE service removes a file from the disk directory and 
releases the space allocated to it. Files that are write-protected or open to any task 
cannot be deleted. 

Applications using the DELETE service must be configured to include RMX/80 
tasks named DELETE, DIRSVC, and DISKIO. (See, in this chapter, the section 
named Defining System Components.) 

Request Message. The DELETE request message must be sent to the RQDELX ex- 
change. 

The format of the DELETE request message is shown in figure 7-11. Asterisks 
denote fields that must be coded by the user task before the message is sent. Shaded 
fields are those set or changed by DFS when it returns the message. 




2 
4 

5 I HOME E XCHANGE 

7 RESPONS E EXCHANGE* 

9 STATUS 
11 



Figure 7-1 1 . DELETE Request Message 



LENGTH is 13. 

TYPE is DFS$DEL(17). 



HOME EXCHANGE is not used by DFS. 



RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. No other task should use 
this exchange. 
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When DFS returns this message, it sets STATUS to indicate the result of the 
DELETE request. Zero is returned if the request is processed successfully; for 
details on nonzero values of STATUS, refer to the "Error Codes" section. The user 
task should check the contents of STATUS after performing the DELETE to ensure 
that the operation has completed normally. 

FILEPTR must provide the address of the File Name Block which specifies the file 
to be deleted. 



Example. The following PL/M code shows how to delete a file. 



"DELETE" EXAMPLE (PL/M) ****/ 



/* FILE NAME BLOCK V 
DECLARE SUPER$FNB(11) 



BYTE DATA 

('F1 SUPER', 0, TXT ); 



/* DELETE MESSAGE*/ 



DECLARE 



DELSMSG 
LINK 
LENGTH 
TYPE 

HOMESEXCHANGE 



STRUCTURE( 

ADDRESS, 

ADDRESS, 

BYTE, 

ADDRESS, 



RESPONSESEXCHANGE ADDRESS, 
STATUS ADDRESS, 
FILEPTR ADDRESS); 
ASSUMED VALUES: */ 

0, 13, DFSSDEL, 0,.WAIT$IHXCH, 0,.SUPER$FNB */ 



DECLARE 



WAITSADDR 



ADDRESS; /* FOR RQWAIT */ 



/* DELETE THE FILE*/ 
CALL ROSEN D(.RQDELX,. DELSMSG); 
WAITSADDR = RQWAIT(.WAIT$EXCH, 0); 
IF DELSMSG. STATUS <> THEN DO; 

/* USER CODE TO HANDLE ERROR GOES HERE */ 

END; 



RENAME Request. The RENAME service changes the name of a file in the direc- 
tory. Files that are write-protected or open to any task cannot be renamed. 

Applications using the RENAME service must be configured to include RMX/80 
tasks named RENAME, DIRSVC, and DISKIO. (See in this chapter, the section 
named Defining System Components.) 



Request Message. 
exchange. 



The RENAME reques. message must be sent to the RQRNMX 



The format of the RENAME request message is shown in figure 7-12. Asterisks 
denote fields that must be coded by the user task before the message is sent. Shaded 
fields are those set or changed by DFS when it returns the message. 
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LE NGTH* 
HOME EXCHANGE 



7 RESPONSE EXCHANGE* 



11 I OLDFILEPTR* 

13 r NEWFILEPTR" 



Figure 7-12. RENAME Request Message 



LENGTH is 15. 

TYPE is DFS$RNM(16). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange 
where the requesting task waits for a response from DFS. No other task should use 
this exchange. 

When DFS returns this message, it sets STATUS to indicate the result of the 
RENAME request. Zero is returned if the request is processed successfully; for 
details on nonzero values of STATUS, refer to the "Error Codes" section. The user 
task should check STATUS after performing the RENAME to ensure that the 
operation has completed normally. 

OLDFILEPTR must provide the address of the File Name Block that specifies the 
name of the file which is to be changed. 

NEWFILEPTR must provide the address of the File Name Block specifying the new 
name of the file. The DEVICENAME of both File Name Blocks must be the same. 
The new name must not be the name of an existing file. (If the name is already in 
use, an error code will be returned in STATUS.) 



Example. The following PL/M code illustrates how to rename a file. 



,.«.. -rename" EXAMPLE (PL/M) ****.' 



/'FILE NAME BLOCKS*/ 
DECLARE OLD$FNB(11) 

NEW$FNB(11) 



BYTE DATA 

('F1 LAUREL', 0,0, 0), 

BYTE DATA 

('F1 HARDY', 0,0, 0,0); 
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I* RENAME MESSAGE */ 

DECLARE RENAME$MSG STRUCTURE! 

LINK ADDRESS, 
LENGTH ADDRESS, 
TYPE BYTE, 
HOMESEXCHANGE ADDRESS, 
RESPONSE$EXCHANGt: ADDRESS, 
STATUS ADDRESS, 
OLDSFILEPTR ADDRESS, 
NEWSFILEPTR ADDRESS); 
/* ASSUMED VALUES: */ 

/* 0, 15, DFSSRNM, 0,.WAIT$EXCH, 0,.OLD$FNB,.NEW$FNB*/ 
DECLARE WAITSADDR ADDRESS; /* FOR RQWAIT */ 



/* CHANGE LAUREL TO HARDY * / 
CALL RQSEND(.RQRNMX,.RENAME$MSG); 
WAITSADDR = RQWAIT(.WAIT$EXCH, 0); 
IF REN AMESMSG. STATUS <> THEN DO; 

/* USER ERROR-HANDLING CODE GOES HERE */ 

END; 



ATTRIB Request. The ATTRIB service allows the user to change the attributes of 
a file. Four attributes are associated with every DFS/ISIS-II file: invisible, system, 
write-protected and format. Only one of these affects DFS: if a file has the write- 
protected attribute set (i.e. it cannot be written on), DFS will not open the file for 
output or update, nor allow it to be renamed or deleted. The other attributes are 
meaningful in the ISIS-II environment and are described in the 1SIS-II System 
User's Guide, 9800306. All the attributes can be set or reset with the ATTRIB ser- 
vice. 



The attributes of a file cannot be changed if the file is open to any task. To create a 
write-protected file, the sequence of operations is OPEN, WRITE, CLOSE, and 
ATTRIB. 

Applications using the ATTRIB service must be configured to include RMX/80 
tasks named ATTRIB, DIRSVC, and DISKIO. (See, in this chapter, the section 
named Defining System Components.) 

Request Message. The ATTRIB request message must be sent to the RQATRX ex- 
change. 

The format of the ATTRIB message is shown in figure 7-13. Asterisks denote fields 
that must be coded by the user task before the message is sent. Shaded fields are 
those set or changed by DFS when it returns the message. 






LINK 


2 


LENGTH* 


4 


TYPE" 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE* 


9 


STATLS 


11 


FILEPTR* 


13 


SWIC* 


15 


VALUIE* 



Figure 7-13. ATTRIB Request Message 
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LENGTH is 17. 

TYPE is DFS$ATR(18). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. No other task should use 
this exchange. 

When DFS returns this message, it sets STATUS to indicate the result of the AT- 
TRIB request. Zero is returned if the request is processed successfully; for details on 
nonzero values of STATUS, refer to the "Error Codes" section. The user task 
should check STATUS after performing the ATTRIB operation to ensure that the 
operation has completed normally. 

FILEPTR must provide the address of the File Name Block specifying the file whose 
attribute is to be changed. 

SWID specifies the attribute to be changed, and must be one of the following codes: 
ATRSINV (0) for Invisible, ATRSSYS (1) for System, ATRSWTP (2) for Write- 
protect, or ATR$FMT (3) for Format. PL/M users may INCLUDE the file AT- 
TRIB. ELT in their programs to define the symbolic values for these codes. 

The low-order bit of VALUE must specify the new value of the attribute identified 
in SWID. If the low-order bit is 1, the attribute is to be set; if it is 0, the attribute is 
to be reset. 



Example. The following coding example sets the write-protected attribute on a file, 
thereby making it read-only (until the attribute is reset). 

/**" "ATTRIB" EXAMPLE (PL/M) ****/ 



/* FILE NAME BLOCK */ 
DECLARE VIRGIN$FNB(11) 



BYTE DATA 

('F1 VIRGIN', 0, 0, 0); 



/'ATTRIB MESSAGE*/ 
STRUCTURE( 
ADDRESS 
ADDRESS, 
BYTE, 
ADDRESS, 



DECLARE ATTRIBSMSG 
LINK 
LENGTH 
TYPE 

HOMESEXCHANGE 
RESPONSESEXCHANGE ADDRESS, 
STATUS ADDRESS, 
FILEPTR ADDRESS, 
SWID ADDRESS, 
VALUE ADDRESS); 
/* ASSUMED VALUES: */ 

/* 0, 17, DFSSATR, 0,.WAIT$EXCH, 0,.VIRGIN$FNB, ATRSWTP, 0FFFFH */ 



DECLARE 



WAITSADDR 



ADDRESS; /* FOR RQWAIT * / 



/* SEND MESSAGE, WAIT FOR COMPLETION, CHECK FOR ERRORS */ 
CALL RQSEND(.RQATRX,. ATTRIBSMSG); 
WAITSADDR = RQWAIT(.WAIT$EXCH, 0); 
IF ATTRIBSMSG. STATUS <> 0THEN DO; 

I* USER ERROR ROUTINE GOES HERE */ 

END; 
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LOAD Request. The LOAD service loads a program segment into RAM from a 
disk file. The loader is a simple non-relocating type that accepts only code that has 
been "located," that is, assigned absolute memory addresses. The segment must be 
located so that its memory can be addressed by the controller (i.e., for iSBC 80/20, 
80/24, and 80/ 10 systems it must be in oifboard RAM). Unlike the ISIS-II loader, 
LOAD does not pass control to the loaded segment, but returns to the user task 
instead. The service is useful for overlay programming — that is, loading routines 
that are not used concurrently into a single memory area. Note that only procedures, 
not main programs, can be loaded. An attempt to execute a main program after 
loading it will cause the system to malfunction. 

Using LOAD successfully requires a thorcugh understanding of the ISIS-II conven- 
tions pertaining to linking and locating object programs. These topics are covered in 
the ISIS-II System User's Guide, 9800306. Note also that LOAD opens the file that 
it loads; the user must provide space for a DFS buffer just as though the user task 
itself were opening the file. (See "Buffers" later in this chapter.) 

Applications using the LOAD service must be configured to include RMX/80 tasks 
named LOAD, DIRSVC, and DISKIO. (See, in this chapter, the section named 
Defining System Components.) 

Request Message. The LOAD request message must be sent to the RQLDX ex- 
change. 

The format of the LOAD message is shown in figure 7-14. Asterisks denote fields 
that must be coded by the user task before the message is sent. Shaded fields are 
those set or changed by DFS when it returns the message. 






LINK 


2 


LENGTH" 


4 


TYPE- 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE" 


9 






FILEPTR" 


13 


BIAIi" I 


15 





Figure 7-14. LOAD Request Message 



LENGTH is 17. 

TYPE is DFS$LD(19). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. No other task should use 
this exchange. 

When DFS returns this message, it sets STATUS to indicate the result of the LOAD 
request. Zero is returned if the request i:> processed successfully; for details on 
nonzero values of STATUS, refer to the "Error Codes" section. The user task 
should check the contents of STATUS following completion of the request to ensure 
that the operation has completed normally. 
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FILEPTR must provide the address of the File Name Block which specifies the file 
to be loaded. 

BIAS must specify a value which DFS is to add (modulo 64K) to the LOAD address 
it obtains from the module. This gives the user the ability to place the module into a 
different (higher) memory location than the address to which it has been located. 
However, LOAD does not adjust the addresses referenced within the module; unless 
the user changes these addresses, it is unlikely that the module will execute correctly. 
Therefore, in most cases the user should specify a BIAS of zero. 

When DFS returns this message, it sets ENTRY to the entry point address of the 
loaded module — or, if the module is not a main program, to zero. Since loading a 
main program has a catastrophic effect on the RMX/80 Nucleus, in practice, zero is 
always returned in this field. (This feature is provided to maintain compatibility with 
ISIS-II.) 



Loading Tasks. You may wish to use the DFS LOAD service to implement overlays 
— that is, to load two or more sections of code that are not used concurrently into a 
single memory area. 

If you wish to overlay code for tasks, you must observe certain RMX/80 re- 
quirements. Task code in an overlay must first be loaded into memory, then the task 
must be created by means of an RQCTSK operation. In addition, you must delete 
the task before loading and creating subsequent tasks in the same memory area. 
RMX/80 requires that the starting address of the actual code for the task be known 
and be available when the RQCTSK operation is performed. Particularly in PL/M, 
this starting address generally will not be the beginning of the overlay segment of 
memory, because constants will precede the code. There are several ways in which 
this problem may be circumvented. 

One method is to declare Static Task Descriptors for all overlayable tasks in your 
main system (resident) code, then "cross-link" your main system code with your 
code for all overlays. This cross-linking is a general method for preparing overlays; 
it may be used for overlays containing tables, procedures, or subroutines rather than 
tasks. It is accomplished as follows: 

1 . Compile (or assemble) all modules which are part of the resident portion. 

2. Link and locate these modules. The LOCATE program will supply a list of 
unresolved external references. 

3. For each overlay segment: 

a. Compile (or assemble) all modules. 

b. Link, including the PUBLICS of the resident linked and located portion. 
(Refer to the ISIS-II Systems User's Guide, 9800306.) 

c. Locate the overlay segment at the predefined overlay starting address. 

4. Use the LINK program again on the located resident portion of your system, 
including the PUBLICs of each file created in step 3. 

Note that code starting addresses must be declared EXTERNAL in the STD's, and 
PUBLIC in the overlay modules. 

Another method is to have your main system (resident) code build the Static Task 
Descriptor dynamically in some portion of RAM, and begin the overlay segment 
with a trivial module containing a single PUBLIC procedure or subroutine that 
takes no parameters and declares no constants. This procedure is to call another pro- 
cedure that performs the actual processing for the task. The trivial module must first 
be linked to the one that does the actual processing. Since the trivial module declares 
no constants, its starting address will be the starting address of the overlay segment. 
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You can include code for more than one task in your overlay segment by making 
your trivial module a series of calls, provided you determine the number of bytes 
needed for each CALL instruction and add the proper offset to the starting address 
in the Static Task Descriptor for each task. 

A third method is to declare the Static Task Descriptor at the beginning of the 
overlay segment. Since the STD is in the same module as the task code, it can be cod- 
ed to include the starting address. Several STD's and the corresponding task code 
may be included in an overlay segment, since the length of an STD is known (always 
17 bytes). 

Linking and locating for the second and third methods is accomplished by perform- 
ing steps 1, 2, and 3 outlined for the first method. Step 4 is not necessary, since the 
LOCATE output from step 2 should not show any unresolved external references 
(except, possibly, for unresolved interrupt exchanges). In addition, the trivial 
module or the module beginning with the Static Task Descriptor(s) must be specified 
first to the LINK command in step 3b, to ensure that the module is located at the 
beginning of the overlay. 

For any of these methods, you can determine the starting address of your overlay 
segments by using the MEMORY array generated by the LOCATE program. To do 
this, you program your resident portion to load overlays into the MEMORY array; 
then when locating in step 3c, you use the MEMORY segment starting address pro- 
vided in the LOCATE output from step 2. A second way to determine the overlay 
starting address is to fix some address that you are sure will be high enough. The 
former method is more economical in terms of memory space, but the latter method 
avoids the necessity to relocate the overlays each time you modify the resident por- 
tion. 



Loading Subroutines. If the code to be loaded does not need to be executed as a 
task, a somewhat simpler technique may be used. This is illustrated by the example 
that follows. 



Example. The following PL/M code illustrates how LOAD can be used to provide a 
simple overlay capability. 



/**** "LOAD" EXAMPLE (PL/M) ***•/ 

/* ASSUME TWO PROCEDURES, ALPHA AND BETA, RESIDE AS 

* OBJECT CODE FILES ON UNIT F1 . BOTH HAVE BEEN LOCATED 

* TO THE SAME ABSOLUTE ADDRESS WHICH THE USER HAS DEDICATED 

* TO AN OVERLAYAREA IN OFFBOARD RAM. THIS TASK LOADS AND 

* EXECUTES ONE OR THE OTHER DEPENDING ON THE SETTING OF A 

* VARIABLE CALLED SWITCH. 
*/ 

/•THE PROCEDURES*/ 

ALPHA: PROCEDURES, P2) EXTERNAL; 

DECLARE <P1 , P2) ADDRESS; 
END ALPHA; 

BETA: PROCEDURE(P3) EXTERNAL; 

DECLARE P3 BYTE; 
END BETA; 
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/* FILE NAME BLOCKS*/ 
DECLARE ALPHA$FNB(11) 

BETA$FNB(11) 



BYTE DATA 
('F1ALPHA',0, 'OBJ'), 
BYTE DATA 
('F1 BETA', 0,0, 'OBJ'); 



/"LOAD MESSAGE*/ 
DECLARE LOAD$MSG 
LINK 



STRUCTURE( 
ADDRESS, 
ADDRESS, 
BYTE, 
ADDRESS, 



LENGTH 
TYPE 

HOMESEXCHANGE 
RESPONSE$EXCHANGE ADDRESS, 
STATUS ADDRESS, 
FILEPTR ADDRESS, 
BIAS ADDRESS, 
ENTRY ADDRESS); 

/* ASSUMED VALUES: */ 

/* 0, 17, DFSSLD, C.WAITJEXCH, 0, 0, 0, */ 



/* MISCELLANEOUS VARIABLES*/ 
DECLARE (SWITCH, P3) BYTE, 

(WAIT,P1,P2) ADDRESS; 

/* CODE TO SET SWITCH, P1 , P2, P3 GOES HERE * / 



IF SWITCH = 1 THEN DO; /* 

LOAD$MSG. FILEPTR = .ALPHASFNB; /* 

CALL RQSEND(.RQLDX,.LOAD$MSG); /* 

WAIT = RQWAIT(.WAIT$EXCH,0); /* 

IF LOAD$MSG. STATUS <> THEN DO; /* 

/* USER ERROR ROUTINE GOES HERE * / 

END; 

ELSE CALL ALPHA(P1,P2); /* EXECUTE ALPHA */ 
END; 



LOAD ALPHA*/ 
POINT TO ALPHA*/ 
SEND LOAD MSG*/ 
WAIT FOR COMPLETION * / 
CHECK FOR ERRORS*/ 



ELSE DO; /* 

LOADSMSG. FILEPTR - .BETASFNB; /* 

CALL RQSEND(.RQLDX,. LOADSMSG); /" 

WAIT = RQWAIT(.WAIT$EXCH, 0); /* 

IF LOADSMSG. STATUS <> THEN DO; /* 

/* USER ERROR ROUTINE GOES HERE 

END; 

ELSE CALL BETA(P3); /* 
END; 



LOAD BETA*/ 
POINT TO BETA*/ 
SEND LOAD MSG*/ 
WAIT FOR COMPLETION */ 
CHECK FOR ERRORS*/ 
*/ 

EXECUTE BETA*/ 



Note that ALPHA and BETA probably refer to PUBLIC variables in the resident 
portion of the system, and the permanently resident code refers to the EXTERNAL 
variables ALPHA and BETA. In this case, steps l through 4 (given in the "Loading 
Tasks" section above) must be followed. Note also that ALPHA and BETA can call 
RQCTSK to create tasks. This implies a fourth technique for loading tasks — i.e., the 
tasks are created by overlayed code rather than by permanently resident code. 



FORMAT Request. The FORMAT service initializes a disk. The disk is labeled, the 
directory and other system files are created (see Appendix E), and the rest of the disk is 
overwritten. (The character written is 0C7H for iSBC 20 1, 202, and 206 controllers, 
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and 0E5H for iSBC 204 controllers.) If tie disk contains any user data, this data is 
destroyed. The disk created is equivalent to an ISIS-11 non-system disk and may be 
used on an 1SIS-II system. 

Applications using the FORMAT service must be configured to include RMX/80 
tasks named FORMAT, DIRSVC, and DISKIO. (See, in this chapter, the section 
named Defining System Components.) 

Request Message. The FORMAT request message must be sent to the RQFMTX ex- 
change. 

The format of this message is shown in figure 7-15. Asterisks denote fields that must 
be coded by the user task before the message is sent. Shaded fields are those set or 
changed by DFS when it returns the message. 






LINK 


2 


LENGTH- 


4 


TYPE" 


5 


HOME EXCHANGE 


7 


REPONSE EXCHANGE" 


9 


sf ATUsis£§§i! : 


11 


FILIzPTR* 



Figure 7-15. FORMAT Request Message 



LENGTH is 13. 

TYPE is DFSSFMT (20). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. No other task should use 
this exchange. 

When DFS returns this message, it sets STATUS to indicate the result of the FOR- 
MAT request. Zero is returned if the request is processed successfully; for details on 
nonzero values of STATUS, refer to the "Error Codes" section. The user task 
should check the contents of STATUS following completion of the request to ensure 
that the operation has completed normally. 

FILEPTR must contain the address of a File Name Block (FNB). The 
DEVICENAME field of the FNB specifies the device on which the disk to be for- 
matted resides. The FILENAME and EXTENSION fields of the FNB contain the 
label to be written on the disk. 

Example. The following coding illustrates r.he use of a FORMAT request. 



/**" "FORMAT" EXAMPLE (PL/M) ****/ 

/* FILE NAME BLOCK */ 

DECLARE SENSOR$FNB(11) BYTE DATA 

"F2SENSORDAT'); 
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/* FORMAT MESSAGE */ 
DECLARE FMTJMSG 



/* 
/* 



LINK 

LENGTH 

TYPE 

HOME5EXCHANGE 



STRUCTURE( 

ADDRESS, 

ADDRESS, 

BYTE, 

ADDRESS, 



RESPONSE$EXCHANGE ADDRESS, 
STATUS ADDRESS, 
FILEPTR ADDRESS); 
ASSUMED VALUES: */ 

0,13, DFSSFMT, 0, .WAITSEX, 0,.SENSOR$FNB */ 



DECLARE WAIT$ADDR 



ADDRESS; /* FOR RQWAIT */ 



ABORT: PROCEDURE(X); / * IN CASE OF ERROR * / 

DECLARE X ADDRESS; 
/* USER ERROR ROUTINE GOES HERE * / 
END ABORT; 

/* FORMATTHE DISK ON DEVICE F2, NAMING IT SENSOR.DAT */ 
CALL RQSEND(.RQFMTX,.FMT$MSG); /'REQUEST SERVICE*/ 

WAIT$ADDR = RQWAIT(.WAIT$EX, 0); /'WAIT*/ 
IF FMTJMSG. STATUS <> /'CHECK FOR ERRORS* / 

THEN CALL ABORT(FMT$MSG. STATUS); 



DISKIO Request. The DISKIO service gives the user the ability to perform disk 
operations directly, bypassing normal DFS directory processing. Data can be read or 
written freely anywhere on the disk. DISKIO is intended for applications which have 
performance and/or memory constraints which preclude the use of the normal 
directory-based I/O services. No analogous capability exists in ISIS-II. 

DISKIO is a powerful facility which has none of the protective features associated 
with OPEN, READ, WRITE, SEEK and CLOSE. Nothing prevents the user from 
destroying system files or files in use by other tasks. Therefore a high degree of 
responsibility is incumbent upon DISKIO users. 

Remember also that when using DISKIO the concepts of files, LENGTH, 
MARKER, and so on do not exist; the user's view of the disk is strictly in terms of 
tracks and sectors. 



The operations which DISKIO can perform are summarized here: 



SEEK: 
FORMAT: 

RECALIBRATE: 
READ: 



Move the head to a specified track. 

Format a specified track; except in the case of track 00, the 
previous track on the diskette must already be formatted (this 
restriction does not apply to hard disks). DFS / ISIS II system 
files (see Appendix E) are not created by this operation. 

Seek track 00. 

Transfer the contents; of a specified sector to memory. 
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VERIFY: 
WRITE: 

WRITE DELETE: 



MOTOR ON: 



Validate the Cyclic Redundancy Check characters of a 
specified sector without transferring data. 

Transfer data from memory to a specified sector. 

Transfer data from memory to a specified sector and mark 
the sector "deleted." Subsequent READ or VERIFY opera- 
tions to the sector will result in an I/O error (see "Error 
Codes" section), but the operations will otherwise be com- 
pleted normally. 

Note. The iSBC 206 disk controller does not support this 
option. If this option is selected for a hard disk, an error will be 
returned. 

(For mini-size drives only.) Turn drive motor on. (For details 
on the use of this oj)eration, refer to "Motor On/Off Opera- 
tions for Mini-Size Drives.") 



MOTOR OFF: (For mini-size drives only.) Turn drive motor off. (For details 

on the use of this operation, refer to "Motor/On/Off Opera- 
tions for Mini-Size Drives.") 



Using Hard Disks. Before using the DISKIO service on a hard disk, you should be 
aware of two major differences between hard disks and diskettes and their respective 
drives and controllers. 



Each hard disk drive can be set for either 128 or 512 bytes per sector; platters on the 
same device have the same sector size. The selection is made, prior to formatting, by 
setting a switch — one for each drive — on the iSBC 206 disk controller. The 512 
bytes per sector may be used only with the DISKIO service. 
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• Each hard disk platter has 800 tracks, as opposed to the 36 or 77 tracks on a diskette. 
For all diskettes, "logical tracks" and physical tracks are identical. Likewise, when 
the 5 1 2 byte/ sector mode is selected, each hard disk physical track is a logical track. 
However, in the 128 byte/sector mode, DISKIO sees each hard disk as having 200 
logical tracks, each composed of four physical tracks. 

Other DFS services and ISIS-1I all require 1 28 byte sectors on hard disks. This implies 
that file structures created on hard disks in the 512 byte/ sector mode are not 
compatible with either ISIS-I1 or the other DFS services. However, for direct data 
manipulation, 512 byte sectoring allows greater speed and larger storage capacity. 

Because DISKIO gives the user intimate control of the disk hardware, moderate 
familiarity with your controller is recommended for successful use of the service. The 
reader is referred to these Intel publications: 

• iSBC 201 Controller: iSBC Diskette Hardware Reference Manual, 9800349 

• iSBC 202 Controller: Double-Density Diskette Controller Hardware Reference 
Manual, 9800420 

• iSBC 204 Controller: Single-Density Diskette Controller Hardware Reference 
Manual, 9800568 

• iSBC 206 Disk Controller Hardware Reference Manual, 9800567 

Applications using the DISKIO service must be configured to include an RMX/80 
task named DISKIO. (See, in this chapter, the section named Defining System 
Components.) 

Request Message. The DISKIO request message must be sent to the RQDSKX ex- 
change. 

The format of the DISKIO message is shown in figure 7-16. Asterisks denote fields 
that must be coded by the user task before the message is sent. Shaded fields are 
those set or changed by DFS when it returns the message. 






LINK 


2 


LENGTH* 


4 


TYPE- 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE* 


9 


STATUS 


11 


DEVICE* 


12 


IOINS* 


14 


NSEC* 


15 


TADR* 


17 


SADR* 


19 


BUFFER* 



Figure 7-16. DISKIO Request Message 

LENGTH is 21. 

TYPE is DFSSDSK (21). 

HOME EXCHANGE is not used by DFS. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange at 
which the requesting task waits for a response from DFS. No other task should use 
this exchange. 
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When DFS returns this message, it sets STATUS to indicate the result of the 
DISKIO request. Zero is returned if the request is processed successfully; for details 
on nonzero values of STATUS, refer to :he "Error Codes" section. The user task 
should check STATUS after each DISKIO request to ensure that the operation has 
completed normally. 

DEVICE must be a number that specifies the disk drive to be accessed by the 
DISKIO operation. The number coded is the offset (index) of the drive entry in the 
Device Configuration Table (see "Preparing the Configuration Module"). For 
example, if the drive to be accessed is the third entry in the Device Configuration 
Table, the number 2 is coded in this field. 



IOINS is a code specifying the instruction to be sent to the device controller, as 
follows: for NO OPERATION; 1 for SEEK; 2 for FORMAT; 3 for RECALIBRATE; 
4 for READ; 5 for VERIFY; 6 for WRITE; 7 for WRITE DELETE; 8 for MOTOR ON; 
or 9 for MOTOR OFF. Codes 10 through 15 are reserved and should not be used. 



NSEC must specify the number of sectors to be transferred in the request. Permissible 
values for NSEC are 1-26 for standard single-density diskettes, 1-52 for standard 
double-density diskettes, 1-18 for mini-size diskettes, 1-36 for hard disks using 128 byte 
sectors, and 1 - 1 2 for hard disks using 5 1 2 byte sectors. The sectors in the request must 
all be on the same physical track. With one exception, this implies that NSEC + 
S ADR - 1 (see below) must not exceed the number of sectors on a physical track. The 
exception concerns hard disks in the 128 bytes/ sector mode; for them, the maximum 
value of NSEC is computed by a) dividing SADR-1 by 36 and then b) subtracting the 
remainder from 36, i.e., NSEC ^ 36 - ((SADR-1) MOD 36). To illustrate the general 
principle, the following request is legal for standard-size double-density diskettes and 
hard disks but is illegal for both standard-size single density and mini-size 
diskettes: NSEC = 10, SADR = 20. 



TADR must specify the track address for the data transfer. Permissible values are 
0-199 for board disks in the 128 byte/ sector mode, 0-799 for hard disks in the 512 
byte/ sector mode, 0-76 for standard-size diskettes, and 0-35 for mini-size diskettes. 



SADR must specify the starting sector address for the data transfer. Permissible 
values are 1-144 for hard disks in the 128 bytes/sector mode and 1-1 2 for hard disks in 
the 512 bytes/ sector mode, 1-26 for standard single-density diskettes, 1-52 for 
standard double-density diskettes, and 1-18 for mini-size diskettes. Again, when this 
parameter is combined with NSEC, the sectors to be transferred must all lie on the 
same track. 



In the event that you want to ACCESS a hard disk platter that has been written on 
another system, you may only be able to reference a block by means of its physical 
location on the platter. For example, you might know that a block resides in sector 6 
of the 315th track on the top of the platter. In order to READ that block via a 
DISKIO request message, you must compute its TADR and SADR. The conversion 
rules which follow are required only if accessing non-DFS disks with DISKIO. They 
assume that the following attributes are known for a record: its recording mode ( 1 28 or 
5 1 2 bytes/ sector); its surface (top or bottom) ; its physical track number m (0-399) on 
that surface; and its physical sector number n (1-36 with 128 byte sectoring and 1-12 
with 512 byte sectoring). If the recording mode is 128 bytes/ sector, the mode for 
conversion is: 
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• if m is even, 

• TADR is m/2 

• if the record is on the top of the platter, SADR is n 

• if the record is on the bottom of the platter, SADR is n + 36 

• if m is odd 

• TADR is (m-l)/2 

• if the record is on the top of the platter, SADR is n + 72 

• if the record is on the bottom of the platter, SADR is n + 108 

If the recording mode is 512 bytes/ sector, the conversion rule is 

• if the record is on the top of the platter, TADR is 2m and SADR is n 

• if the record is on the bottom of the platter, TADR is 2m +1 and SADR is n 

Thus, by the first of these rules, a record which had been written in 128 byte/ sector 
mode, in sector 6 of track 315 of the top of a platter has 

TADR = 157 [ = (315 - l)/2] 



and 



SADR = 78 [ = 6 + 72]. 



BUFFER must specify the starting address of the memory area to which or from 
which the data is to be transferred. The buffer must be located in controller- 
addressable memory. (See "Defining System Components" later in this chapter.) All 
DISKIO transfers are done by DMA. Since DISKIO operations always transfer 
whole sectors, the length of the buffer should be a multiple of the sector length, 
normally 128 bytes (512 bytes is a hard disk option). The user task is responsible for 
ensuring that the buffer length is compatible with the DISKIO request. 

If the DISKIO request is FORMAT, it is imperative that some space in the buffer be 
filled in with sector identification; this is required by the controller. Two bytes must be 
reserved for each sector on the track for iSBC 201, 202, and 206 controllers, or four 
bytes for each sector for iSBC 204 controllers. (Consult the appropriate controller 
Hardware Reference Manual for more detailed coverage of this topic, including how 
to fill in the sector identification bytes.) 

In the case of hard disks using 128 byte sectoring, it must be noted that each FORMAT 
request to DISKIO formats one physical track of 36 sectors, on one surface of the disk. 
The track is selected by the combined values of TADR and SADR; to format one 
logical track, use the TADR for that logical track, and make four FORMAT requests 
with SADR values of 1, 37, 73, and 109, respectively. 

Example. The DISKIO coding example performs the same direct update function 
that was previously illustrated in the SEEK example. It shows the additional 
housekeeping functions for which the user is responsible when using the DISKIO 
service. The data for the experiments is assumed to begin on track 10, sector 01; the 
disk is standard-size single-density. Note that the entire 100-byte record is read and 
rewritten. This is not strictly necessary in this example, because only the first byte of 
the record is updated (only the sector containing the first byte of the record needs to be 
accessed). It does illustrate, however, what would be required if other fields were 
to be updated at the same time. 
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/♦*** "DISKIO" EXAMPLE (PL/M) ***•/ 

UPDATETEMP: PROCEDURE(EXPERIMENT,NEW$TEMP); 
DECLARE (EXPERIMENT, NEW$TEMP)E1YTE; 

/*DISKIO MESSAGE*/ 



DISKIOSMSG 


STRUCTURE( 


LINK 


ADDRESS 


LENGTH 


ADDRESS, 


TYPE 


BYTE, 


HOME$EXCHANGE 


ADDRESS, 


RESPONSESEXCHANGE 


ADDRESS, 


STATUS 


ADDRESS, 


DRIVE 


BYTE, 


IOINS 


ADDRESS, 


NSEC 


BYTE, 


TADR 


ADDRESS, 


SADR 


ADDRESS, 


BUFADR 


ADDRESS); 



/•ASSUMED VALUES:*/ 

/*0,21, DFSSDSK, 0, .WAITSEX, 0, 0, 0, 0, 0, 0, */ 



/* BUFFER SPACE FOR TWO SECTORS DEFINED IN C.A.M. MODULE */ 
DECLARE (BUFFER1,BUFFER2)(128) BYTE EXTERNAL; 

DECLARE WAIT$ADDR ADDRESS; /'RQWAIT*/ 

DECLARE /'VARIABLES USED TO COMPUTE DISK ADDRESS OF FIRST BYTE OF RECORD* / 

(TRACKNO,SECTOR,TRACK$OFFSET, 
SECTORSOFFSET, BYTENO) ADDRESS; 

/* TAKE CARE OF ERRORS */ 

ERRORSHANDLER: PROCEDURE(X); 
DECLARE X ADDRESS; 

/* USER CODE TO PROCESS ERRORS GOES HERE * / 
END ERRORSHANDLER; 

/* NOTE THAT THE ENTIRE RECORD IS READ EVEN THOUGH ONLY THE 

* FIRST BYTE IS UPDATED. DRIVE IS DEFINED BY FIRST ENTRY 

* IN DEVICE CONFIGURATION TABLE (NOT DECLARED IN EXAMPLE). 
*/ 

/* DETERMINE LOCATION OF BEGINNING OF RECORD*/ 
BYTENO = ((EXPERIMENT - 1) * 100) + 1; 
TRACK$OFFSET = BYTENO / 128; 
TRACKNO = (TRACK$OFFSET / 26) < 10; 
SECTOR = (TRACK$OFFSET MOD 26) + 1; 
SECTOR$OFFSET = (BYTENO MOD 128) - 1; 
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/* IF RECORD SPANS TWO TRACKS, READ THE FIRST SECTOR OF THE 
* SECOND OF THOSE TRACKS INTO BUFFER2 

*/ 

IF SECTORSOFFSET > 28 AND SECTOR = 26 THEN DO; 



DISKIO$MSG.IOINS = 4; 
DISKIO$MSG.NSEC = 1; 
DISKIOSMSG.TADR = TRACKNO + 1 ; 
DISKIOSMSG.SADR = 1; 
DISKIOSMSG.BUFADR - .BUFFER2; 
CALL RQSEND(.RQDSKX,.DISKIO$MSG) 
WAITSADDR = RQWAIT(.WAIT$EX,0); 
IF STATUS <>0 THEN 

CALL ERROR$HANDLER(.DISKIO$MSG); 
END; 



/'DO A READ * / 
/*READ ONE SECTOR * / 
/'DATA IS ON NEXT TRACT * / 
/•DATA IN FIRST SECTOR * / 
/•PUT IT IN BUFFER2 * / 
/'SEND MSG * / 
/"WAIT UNTIL DONE * / 
/•CHECK FOR ERRORS */ 



/* READ SECTOR CONTAINING BEGINNING OF RECORD INTO BUFFER1. 

* IF RECORD SPANS TWO SECTORS ON SAME TRACK, READ THE SECOND 

• SECTOR INTO BUFFER2 WITH THE SAME REQUEST 
*/ 



IF SECTORSOFFSET > 28 AND SECTOR < 26 

THEN DISKIOSMSG.NSEC = 2 

ELSE DISKIOSMSG.NSEC = 1; 
DISKIO$MSG.IOINS = 4; 
DISKIOSMSG.TADR = TRACKNO; 
DISKIOSMSG.SADR = SECTOR; 
DISKIOSMSG.BUFADR = .BUFFER1; 
CALL RQSEND(.RQDSKX,.DISKIO$MSG); 
WAITSADDR = RQWAIT(.WAITSEX,0); 
IF STATUS <>0 THEN 

CALL ERRORSHANDLER(.DISKIOSMSG); 

/* UPDATE THE RECORD * / 

BUFFER(SECTORSOFFSET) = NEWSTEMP; 



/* REWRITE BUFFER1 (AND BUFFER2 IF IT IS ON THE SAME TRACK) * / 
DISKIOSMSG.IOINS = 6; /*NSEC,TADR,SADR ARE STILL SET*/ 
CALL RQSEND(.RQDSKX,.DISKIO$MSG); 
WAITSADDR = RQWAIT(.WAITSEX,0); 
IF STATUS <>0 THEN 

CALL ERRORSHANDLER(.DISKIOSMSG); 



/* REWRITE BUFFER2 IF IT IS ON A DIFFERENT TRACK */ 
IF SECTORSOFFSET > 28 AND SECTOR = 26 THEN DO; 
DISKIOSMSG.TADR = TRACKNO + 1 ; 
DISKIOSMSG.SADR = 1; 
DISKIOSMSG.BUFADR = .BUFFER2; 
CALL RQSEND(.RQDSKX,.DISKIO$M3G); 
WAITSADDR = RQWAIT(.WAIT$EX,0); 
IF STATUS <>0 THEN 

CALL ERRORSHANDLER(.DISKIOSMSG); 
END; 

END UPDATESTEMP; 
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Error Codes 

As a part of processing each user request, DFS places a code in the STATUS field of 
the user's request message which indicates the result of the request. This code is 
placed in the low-order byte of STATUS. Your application task should always check 
this code before processing any data associated with the request. 

Table 7-4 lists the error codes that may be. found in the low-order byte of STATUS. 
These error codes can be considered to be an extension of the codes associated with 
ISIS-II error messages. Most ISIS-II error codes are applicable to problems that can 
occur in DFS and are retained. Those that are not applicable are deleted, although 
the number associated with each such number is not reassigned. New error codes 
that are unique to DFS are added after the last ISIS-II code. Among those errors 
that are common to both systems, there is one major change: errors that are con- 
sidered fatal in ISIS are not so considered in DFS. 

If error 24 (input/ output error) occurs, D FS places a code in the high-order byte of 
STATUS to identify the type of 1/ O error. The 1/ O error codes that may be found in 
the high-order byte of STATUS are listed in table 7-5. These codes correspond to the 
error codes supplied by the disk controller. 

Consult the appropriate Hardware Reference Manual for more information on I/O 
errors. Note that when an I/O error occurs, DFS retries the operation three times 
before returning an error indication; therefore there is no point in the user task's 
retrying the operation. 

Table 7-6 indicates which types of errors can occur for each type of DFS service re- 
quest. 



Table 7-4. DFS Error Codes (Low-Order Byte of STATUS) 



CODE 


MEANING 





No error detected 


4 


Illegal FILENAME specified in File Name Block 


5 


DEVICENAME in File Name Block not in Device Configuration 
Table 


6 


Attempt to write to a file opened for input 


7 


No more space on disk 


8 


Attempt to read a file opened for output 


9 


No more room in disk direc tory 


10 


File Name Blocks in RENA VIE request do not specify same device 


11 


Cannot rename file; name already in use 


12 


File already open 


13 


No such file 


14 


Attempt to open a write-protected file for output or update, or 
attempt to delete or rename a write-protected file 


16 


Incorrect object program format 


18 


Unrecognized message TYPE 
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Table 7-4. DFS Error Codes (Low-Order Byte of STATUS) - (continued) 



CODE 


MEANING 


20 


Attempt to seek backward past beginning of file 


22 


Illegal ACCESS in OPEN message 


24 


Input/output error on disk 


26 


Illegal SWID in ATTRIB message 


27 


Illegal MODE in SEEK message 


30 


Drive not ready 


31 


Attempt to seek on file open for output 


32 


Attempt to delete an open file 


35 


Attempt to seek past end of file opened for input 


40 


Request sent to wrong exchange 


41 


Insufficient free memory space to open file 


42 


DRIVE specified in DISKIO request is not in Device Configuration 
Table 


43 


Drive timeout - the drive has not responded to an I/O request within 
a set period of time (10 seconds for the iSBC 80/20, 80/24, or 80/30 
systems; for 80/10 systems, refer to Appendix G.) 


44 


SEEK request with SEEi< not present in system 


45 


Format driver missing 


46 


Illegal DISKIO operation (for hard disks only) 


47 


Illegal sectoring mode (lor hard disks only) 


Table 7-5. DFS I/O Error Codes (High Order Byte of Status) 


CODE 


MEANING 


1H 


Deleted record 


2H 


Cyclic Redundancy Check character error (data field) 


3H 


Invalid address mark 


4H 


Seek error 


8H 


Address error 


OAH 


Cyclic Redundancy Check character error (ID field) 


OEH 


No address mark 


OFH 


Incorrect data address mark 


10H 


Data overrun or underrur 


20H 


Write protect 


40H 


Write error 


80H 


Not ready 
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Table 7-6. Disk Filt: System Error Matrix 



CODE 


OPEN 


READ 


WRITE 


SEEK 


CLOSE 


DELETE 


RENAME 


ATTRIB 


FORMAT 


LOAD 


DISKIO 


4 


X 










x 


x 


x 


x 


x 




5 


x 










x 


x 


X 


x 


x 




6 






x 


















7 


x 




x 


x 
















3 




x 




















q 


x 






















10 














x 










11 














x 










12 


x 






















13 


x 










x 


x 


X 




x 




m 


A 










Y 
A 


Y 
A 










1fi 




















x 




I O 
























on 








Y 

A 
















00 


A 






















OA 


x 


x 


x 


x 


x 


x 


x 


x 


x 


x 


Y 




CO 
















x 




07 

CM 








Y 
A 
















30 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


31 








X 
















32 












X 












35 








X 
















40 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


41 


X 






















42 






















X 


43 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


44 








X 
















45 


















X 






46 






















X 


47 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 





* Since OPEN, READ, etc. represent valid message TYPES, error 18 cannot occur for valid DFS requests. 



Information For ICU80 Users 

This section contains information that you should read before configuring with the 
Interactive Configuration Utility. 

DISK Controllers 

Each controller must have its own interrupt level — i.e., no two controllers can 
share an interrupt level — and the corresponding interrupt exchange must be 
declared in your system. 



Assigning DFS Task Priorities. Refer to "Assigning Priority Levels" in the 
configuration section of Chapter 3 for general suggestions on this subject. In 
addition, certain rules and guidelines apply to assigning priorities to DFS service and 
controller tasks. 

In general, the only DFS tasks which should be assigned priorities numerically lower 
than 129 (those priorities corresponding to interrupts) are controller tasks. Each of 
these tasks should be given a software priority corresponding to the hardware inter - 
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rupt level which has been assigned to the controller. Generally, high-speed devices 
such as disk controllers are run at relatively high (numerically low) interrupt levels 
such as 2 or 3. The software priorities which correspond to these interrupt levels are 
33 through 48 and 49 through 64, respectively. 

DFS service tasks should be assigned priorities in the range 129-254. Within this 
range DISKIO should be given the highest priority, and other tasks should be given 
descending priorities based on their performance characteristics. 



Allocating Buffers. If the user opens a file or uses the LOAD service (which itself 
opens a file), then buffer space must be made available to DFS. 

There are two ways to allocate this space: statically and dynamically. In static buffer 
allocation, the user specifies the maximum number of files that will ever be open at 
the same time and supplies a controller-addressable RAM area which DFS manages 
as a buffer pool. For each file among those that are open simultaneously, 400 bytes of 
controller addressable memory are needed. In dynamic memory allocation, the user 
includes the Free Space Manager in the system, and DFS acquires and releases buffer 
space through the Free Space Manager. 

The Free Space Manager itself takes a certain amount of memory (see Appendix E), 
and the user must decide whether this "overhead" is justified in the application. If the 
Free Space Manager is needed in the application for purposes other than DFS buffer 
allocation, then dynamic buffer allocation should generally be specified during 
configuration. No extra space, and very little time, is required for the Free Space 
Manager to manage buffer allocation. Depending on the characteristics of the 
application, when files are closed the Free Space Manager may be able to use the 
released space for other purposes. 



Note that if dynamic buffer allocation is selected, the user must ensure that DFS 
always receives memory which is controller-addressable. As discussed under 
"Memory Requirements" at the beginning of this chapter, in i SBC 80/20-, 80/24-, 
and 80/10-based systems, only off-board RAM is controller-addressable. In 80/20, 
80/24, or 80/ 10 systems, your tasks should therefore give the Free Space Manager 
only off-board memory when it is initialized. On-board memory may be given to the 
Free Space Manager only if the user can ensure that it will never be allocated to DFS. 
(If the amount of contiguous on-board memory is less than what is needed to open a 
file — see Appendix D — this will be true.) These restrictions do not apply to iSBC 
80/30-based systems, since 80/30 on-board RAM is controller-addressable. 

If the Free Space Manager is not otherwise needed in the application, then static buf- 
fer allocation should usually be specified. The maximum number of concurrently 
open files should be noted on the worksheet (remember that LOAD opens a file). 

If no files are ever opened or loaded, then no DFS buffers are required, and you 
should specify that "number of files" is zero. 

The following DFS services require user buffers: READ, WRITE and DISKIO (the 
address of the user buffer is contained in the BUFFER field of the requesting 
message). In the case of READ and WRITE, a user buffer must be supplied in addi- 
tion to the buffer needed by DFS to open the file. The question to be answered when 
configuring is whether these buffers need to be located in controller-addressable 
memory. This in turn is dictated by whether the controller will ever do a Direct 
Memory Access of the buffer. In the case of DISKIO requests this is always true, so 
for iSBC 80/ 10, 80/20, and 80/24 systems, DISKIO buffer space must always be 
located off-board. 
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In the case of READ and WRITE, the rule is as follows: a DMA transfer to/ from the 
user buffer occurs whenever MARKER is at a sector boundary and the request is for 
128 bytes or more. Another way of stating this is that DMA transfers are done in 
whole sectors. If a DMA transfer can occur, then the user buffer must be located in 
controller-addressable memory. If a DMA transfer cannot occur (e.g., if transfers are 
always less than 128 bytes), then the user buffer in 80/20, 80/24, or 80/ 10 systems can 
be located on- or off-board (access is faster if it is on-board). It is possible to locate 
some user buffers on-board and some off board. Note that DMA data transfers are 
significantly faster than if the processor places the data in the user's buffer one byte 
at a time. If the application is designed to use DMA, throughput is maximized. 

Summary of DFS Configuration Information 

Table 7-7 summarizes the main facts yoj need when using the ICU80 utility. 



Table 7-7. Configuration Information for DFS Service and Controller Tasks 



TASK 




INITIAL 


STACK 




DEFAULT 


NAME 


P.C. 


LENGTH 


PRIORITY 


EXCHANGE 


DISKIO 


'DISKIO' 


RQPDSK 


72 




RQDSKX 


Directory Services 


'DIRSVC 


RQ 3 DIR 


72 




RQDIRX 


ATTRIB 


'ATTRIB' 


RQ=>ATR 


88 




RQATRX 


DELETE 


'DELETE' 


RQPDEL 


88 




RQDELX 


FORMAT 


'FORMAT' 


RQPFMT 


88 




RQFMTX 


LOAD 


'LOAD ' 


RQPLD 


88 




RQLDX 


RENAME 


'RENAME' 


RQPRNM 


88 




RQRNMX 


ISBC 201 and 202 Controllers 




RQHD1 


104 






iSBC 204 Controllers 




RQHD4 


104 






iSBC 206 Controllers 




RQHD6 


104 
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CHAPTER 8 
ANALOG HANDLERS 



General Description 

The Analog Handlers provide analog input and output services for users whose 
systems interface with the iSBC 711, iSBC 724, and iSBC 732 analog boards. The In- 
put Handler performs repetitive, sequential, and random channel input; the Output 
Handler performs random channel output. 

Use of the Analog Handlers requires a basic degree of familiarity with the analog 
board(s) being used. This section is written assuming such familiarity. For details on 
the analog boards, refer to the appropriate Hardware Reference Manuals: 

• iSBC 71 1 Analog Input Board Hardware Reference Manual, 9800485 A 

• iSBC 724 Analog Output Board Hardware Reference Manual, 9800486A 

• iSBC 732 Combination Analog Input/Output Board Hardware Reference 
Manual, 9800487A 

Functions Provided 

Repetitive Channel Input. This function repetitively samples a single A/D channel 
up to 254 times, applying the same gain «:ach time. The data values obtained are 
placed in a user-specified array. 

Sequential Channel Input with Single Gain. This function samples a sequence of 
consecutively numbered A/D channels, applying the same gain to every sample. The 
data values obtained are placed in a user-spucified array. 

Sequential Channel Input with Variable Gain. This function samples a sequence 
of consecutively numbered A/D channels, applying an individually specified gain to 
each sample. The data values obtained are placed in a user-specified array. 

Random Channel Input. This function samples a set of A/D channels whose order 
is user-specified, applying an individually specified gain to each sample. The data 
values obtained are placed in a user-specified array. 

Random Channel Output. This function simply sets a number of D/A channels. 
Both the channels and their outputs are user-specified. 

Use Environment 

The Analog Handlers run under RMX/80 in an iSBC 80/20, 80/24, 80/30, or 80/ 10 
environment. The Handlers interface with an iSBC 711, iSBC 724, or iSBC 732, or a 
combination of these boards. 

A single version of the Analog Handlers supports the iSBC 80/20, 80/24, 80/30, and 
80/10. 

Memory and Hardware Requirements 

The Analog Input Handler requires less than 600 bytes of code space and less than 
30 bytes of data space, and uses a 34-byte stack. The Analog Output Handler re- 
quires less than 200 bytes of code space and less than 20 bytes of data space, and uses 
a 32-byte stack. Refer to Appendix D for exact byte counts. 
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Analog boards are factory configured with certain features fixed, such as the ad- 
dress of the base register on the A/D or D/A converter. If more than one analog 
board is installed in his system, the user must reconfigure the base register address 
of each additional board as described in the Hardware Reference Manual for that 
board. (Refer to the list of manuals at the beginning of this chapter.) 

How the Analog Handlers Operate 

The Analog Handlers extension to RMX/80 consists of two tasks, an Input Handler 
and an Output Handler. These tasks are independent of each other, so that if only 
analog input or only analog output is needed, only one of the tasks need be con- 
figured in the system. 

As shown in figure 8-1, each task waits at an exchange — RQAIEX for the Input 
Handler, RQAOEX for the Output Handler — for a request message from the user 
task. When an Analog Hander task receives a message, it performs the appropriate 
operation, modifies the request message, and returns the message to the appropriate 
user-defined response exchange, designated in figure 8-1 as RESP$IEX or 
RESP$OEX. 



/ZZJ 




ANALOG 
OUTPUT 
HANDLER 





RESPSOEX 



USER 




TASK 









Figure 8-1 . Exchanges for Analog Handlers 



Using the Analog Handlers 

General Usage Considerations 

The sequence of events that occurs when a user task sends a message to the exchange 
of an Analog Handler depends on the relative priorities of the user task and the 
Handler. The software priority of each Handler may be specified by the user. In 
most applications it probably should be higher than the user task. This means that 
when the user task sends a request message to an Analog Handler exchange, the 
Handler will begin running immediately. However, if the user task is assigned a 
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higher priority, sending a message will make the Handler ready, and it will begin to 
run when it becomes the highest-priority ready task. 

While each operation is in progress, the Analog Handler has control of the pro- 
cessor. This means that other processing cannot be accomplished concurrently with 
the analog input or output operation. However, the Analog Handlers do not disable 
interrupts, and servicing of a higher-priority interrupt may increase the time interval 
between two input samplings or the presentation of two" analog outputs. If this is not 
acceptable, the tasks should run at a software priority in the range 1-16 (1-4 on the 
iSBC 80/30 and 1-128 on the iSBC 80/10) in order to lock out all interrupts. Note 
that in an iSBC 80/10 system with an external clock running, this may result in mis- 
sing one or more clock ticks if the time base (time between clock interrupts) is less 
than the time required to perform the input or output. 



Error Conditions 

The Analog Handler tasks do not check the validity of input parameters, and the 
operation resulting from invalid arguments is undefined. Such error checking has 
been omitted in order to minimize response time. 

The only hard error detected is failure of the A/D converter to respond. If this oc- 
curs, the Analog Input Handler sets the STATUS field in the request message to 3 
before it returns the message to the response exchange. 



Performance Data 

Use of the Analog Handlers with RMX/80 considerably reduces the programming 
time and effort required for your system. However, the Analog Handlers do in- 
troduce some system overhead, and thus may not be an acceptable solution for 
systems in which speed is extremely critical. 

Table 8-1 provides data on the time required to process an analog input or output re- 
quest of each type. The setup time is incurred once for the request; the time per itera- 
tion is incurred once each time a channel is sampled. Thus, for example, a request 
for repetitive sampling of a particular channel 10 times would take 2.28 + 10(0.22) 
msec, or 4.48 msec. These performance times apply when the code is in on-board 
RAM or ROM, and the data is in off-board RAM. Setup times include both the RQ- 
SEND and the RQWAIT operations as well as the analog processing. 



Table 8-1 . Performance Times for Analog Handler Functions 



Function 


Setup Time 
(msec) 


Time per 
Iteration 
(msec) 


Repetitive Channel Input 


2.28 


0.22 


Sequential Channel Input with 
Single Gain 


2.28 


0.22 


Sequential Channel Input with 


2.41 


0.29 


Variable Gain 


Random Channel Input 


2.41 


0.29 


Random Channel Output 


1.9 


0.3 



Requests for Analog Input and Output 

To request analog input or output processing, the user task must create and send a 
message to the appropriate Analog Handler exchange — RQAIEX for input, or 
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RQAOEX for output. The request message includes pointers to other data struc- 
tures, which must be built before the message is sent. This section describes the re- 
quest message and other data structures associated with each function, and also 
gives an example showing how to code a request for that function. 

The coding examples are intended to be succinct illustrations of the essential use of 
each input or output function; they should not be construed as complete, executable 
user tasks. In order to make the usage of the services as clear as possible, the ex- 
amples have been coded in PL/M. (These examples imply use of the INCLUDE file 
AITYP.ELT or AOTYP.ELT for symbolic values of message types; refer to Appen- 
dix A.) The first example (repetitive channel input), has also been coded in assembly 
language to show the corresponding constructs. There is a high degree of com- 
monality in the user interfaces to the various Analog Handler functions; it should be 
easy for assembly language programmers to "translate" the other examples as 
necessary. 

Each example includes an error routine that is empty except for a comment that 
states that user code should replace the comment. This approach has been taken in 
order to emphasize that user tasks must be prepared for errors, but that the tech- 
nique used for error processing is necessarily application-dependent. Error routines 
should, at least, check for a STATUS value of 3, indicating failure of the converter 
to respond. The user task may check for input values that might be invalid and/ or 
for an ACTUAL value that differs from COUNT. 



Repetitive Channel Input. 

Request Message Format. A task requesting that a single A/D channel be sampled 
repetitively creates and sends (to the RQAIEX exchange) a message with the format 
shown in figure 8-2. Asterisks denote fields that must be coded by the user task 
before the message is sent. Shaded fields are those set or changed by the Analog In- 
put Handler when it returns the message. 




2 
4 

5 I HOME EXCHANGE 

7 RESPONSE EXCHANGE" 

9 STA TUS 
11 BASE REG POINTER* 

13 CHAN-GAIN- | not used 
15 DATA ARRA/ POINTER" 

17 
19 



Figure 8-2. Request Message for Repetitive Channel Input 



LENGTH is 21. 



TYPE is AIREP (30). 



HOME EXCHANGE is not used by the Analog Input Handler. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange to 
which the Analog Input Handler is to send the message when the operation is com- 
pleted. 
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When the Analog Input Handler returns this message, STATUS is set to 1, 2, 3, or 4, 

to indicate one of the following conditions: 

1: all data collected. 

2: (reserved for future use.) 

3: operation aborted; converter did not respond. 

4: (reserved for future use.) 

BASE REG POINTER must specify the address of the Command-Status Register of 
the selected A/D converter. 

CHAN-GAIN must specify the number of the channel to be sampled and the gain 
that is to be applied to each sample. Its format is: 



7 6 5 4 ° 

| GAIN | CHANNEL NO. | 



CHANNEL NO. , bits 0-4: a number 0-31 . 

GAIN, bits 6-7: a value of 0, 1, 2, or 3; represents a gain of xl, x2, x4, or x8, 

respectively. 

Bit 5 is ignored. 

DATA ARRAY POINTER must specify the address of the array to receive the 
sampled inputs. The number of elements in the array is equal to COUNT, and each 
element is two bytes. The Analog Input Handler will store the i tri sample in the ith 
element of the array (recall that the i 1 * 1 element of the array has array index i-1) , in 
the following format: 



15 43 

DATA I I 



Each element represents the actual value read from the A/D converter Data Register 
— 12 bits of data, followed by 4 zeros in the least significant bit positions. The 
voltage level corresponding to the 12-bit number is dependent upon the full-scale 
voltage range and the binary code, both of which are jumper-selected by the user as 
described in the Hardware Reference Manual for the analog input board. (See list of 
manuals at the beginning of this chapter.) 

COUNT must specify the number of samples to be collected. Permissible values are 
1-254. 



When the Analog Input Handler returns this message, ACTUAL is set to the actual 
number of samples collected. 

Example. The following coding example takes five samplings from a single analog 
channel (channel 31) and stores the result in the array CURRSTEMP (CTEMP in 
assembly language). The gain applied is x2. This code could be used to update the 
roller temperature reading in the paper factory process control example discussed in 
Chapter 1 . 
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/* EXAMPLE OF REPETITIVE CHANNEL INPUT (PL/M) */ 



/* REQUEST MESSAGE*/ 

DECLARE REP$INP$MSG STRUCTURE 

(LINK ADDRESS, 

LENGTH ADDRESS, 

TYPE BYTE, 

HOMESEXCHANGE ADDRESS, 

RESPONSESEXCHANGE ADDRESS, 

STATUS ADDRESS, 

BASE$REG$POINTER ADDRESS, 

CHANSGAIN BYTE, 

UNUSED BYTE, 

DATA$ARRAY$POINTER ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS); 
/* ASSUMED CONTENT OF MESSAGES * / 
/* 0, 21, AIREP, 0,.RESP$EX, 0, 0F700H, 01011111B, 
0,.CURR$TEMP,5,0*/ 



/* EXCHANGE DEFINITION */ 

DECLARE EXCHANGE$DESCRIPTOR LITERALLY 'STRUCTURE 

(MESSAGESHEAD ADDRESS, 

MESSAG E$TAIL ADDRESS, 

TASK$HEAD ADDRESS, 

TASKSTAIL ADDRESS, 

EXCHANGESLINK ADDRESS)'; 



/* ANALOG HANDLER AND RESPONSE EXCHANGES */ 
DECLARE RQAIEX EXCHANGESDESCRIPTOR EXTERNAL; 
DECLARE RESPSEX EXCHANGESDESCRIPTOR; 



/* DATA STORAGE*/ 

DECLARE CURRSTEMP (5) ADDRESS; 

/* POINTER TO RETURN MESSAGE*/ 
DECLARE T1 ADDRESS; 

/* EXTERNAL PROCEDURES */ 
RQCXCH: PROCEDURE (X) EXTERNAL; 

DECLARE X ADDRESS; 
END RQCXCH; 

RQSEND: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQSEND; 

RQWAIT: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQWAIT; 

/* BUILD RESPONSE EXCHANGE */ 
CALL RQCXCH(. RESPSEX); 

/* SEND INPUT REQUEST, WAIT FOR RESPONSE */ 
CALL RQSEND(. RQAIEX, .REP$INP$MSG); 
T1 = RQWAIT(.RESP$EX, 0); 

/* USER ERROR CHECKING ROUTINE GOES HERE */ 
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EXTRN RQAIEX, RQCXCH, ROSEND, RQWAIT 



RESPEX: 
CTEMP: 

INPMSG: 



DSEG 

DS 

DS 

DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 
DS 

CSEG 



10 

5 

2 
2 
1 
2 
2 
2 
2 
1 
1 
2 
2 
2 



RESPONSE EXCHANGE 
TEMPERATURE READING 

REQUEST MESSAGE 

LINK 

LENGTH 

TYPE 

HOME EXCHANGE 
RESPONSE EXCHANGE 
STATUS 

POINTER TO I3ASE REGISTER 
CHANNEL-GAIN 
NOT USED 
POINTER TO DATA 

;COUNT 

;ACTUAL COUNT 



; ASSUMED CONTENTS: 0, 21, 30, 0, RESPEX, 0, 

; 0F7C0H, 01011111 B, 0, CRNTMP, 5, 

; BUILD RESPONSE EXCHANGE 

LXI B, RESPEX ;ADDR WHERE EXCH IS TO BE BUILT 

CALL RQCXCH ; BUILD IT 



SEND INPUT REQUEST, WAIT FOR RESPONSE 



LXI D.INPMSG 
LXI B, RQAIEX 
CALL RQSEND 
LXI D,0 
LXI B, RESPEX 
CALL RQWAIT 



ADDR OF INPUT REQUEST MESSAGE 
ADDR OF ANALOG INPUT EXCHANGE 
SEND MESSAGE 
NO TIME LIMIT 

ADDR OF RESPONSE EXCHANGE 
WAIT 



; USER ERROR CHECKING ROUTINE GOES HERE 
Sequential Channel Input with Single Gain. 

Request Message Format. A task requesting that a sequence of consecutive chan- 
nels be sampled, with the same gain applied to each sample, creates and sends (to 
RQAIEX) a message with the format shown in figure 8-3. Asterisks denote fields 
that must be coded by the user task before the message is sent. Shaded fields are 
those set or changed by the Analog Input Handler when it returns the message. 






LINK 


2 


LENGTH" 


4 


TYPE* 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE" 


9 


STAT I S 


11 


BASE REG POINTER* 


13 


CHAN-GAIN" | not used 


15 


DATA ARRAY JOINTER* 


17 


COUNT" 


19 


ACTUAL 



Figure 8-3. Request Message for Sequential Channel Input with Single Gain 
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LENGTH is 21. 
TYPE isAISQS (31). 

HOME EXCHANGE is not used by the Analog Input Handler. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange to 
which the Analog Input Handler is to send the message when the operation is com- 
pleted. 

When the Analog Input Handler returns this message, STATUS is set to 1, 2, 3, or 4, 

to indicate one of the following conditions: 

1: all data collected. 

2: (reserved for future use.) 

3: operation aborted; converter did not respond. 

4: (reserved for future use.) 

BASE REG POINTER must specify the address of the Command-Status Register of 
the selected A/D converter. 

CHAN-GAIN must specify the number of the first channel to be sampled and the 
gain that is to be applied to each sample. Its format is: 

7 6 5 4 

| GAIN | f CHANNEL NO. | 

CHANNEL NO. , bits 0-4: a number 0-31 . 

GAIN, bits 6-7: a value of 0, 1, 2, or 3; represents a gain of xl, x2, x4, or x8, 

respectively. 

Bit 5 is ignored. 

DATA ARRAY POINTER must specify the address of the array to receive the 
sampled inputs. The number of elements in the array is equal to COUNT, and each 
element is two bytes. The Analog Input Handler will store the i tn sample in the i tn 
element of the array (recall that the i*h element of the array has array index i-1), in 
the following format: 

15 4 3 

| DATA | | 

Each element represents the actual value read from the A/D converter Data Register 
— 12 bits of data, followed by 4 zeros in the least significant bit positions. The 
voltage level corresponding to the 12-bit number is dependent upon the full-scale 
voltage range and the binary code, both of which are jumper-selected by the user as 
described in the Hardware Reference Manual for the analog input board. (See list of 
manuals at the beginning of this chapter.) 

COUNT must specify the number of channels to be sampled. CHANNEL NO. plus 
COUNT must not exceed 32. 

When the Analog Input Handler returns this message, ACTUAL is set to the actual 
number of channels sampled. 

Example. The following coding example samples analog channels through 31, 
which are attached to identical devices (or, at least, devices to whose output the same 
gain can be applied). The results are stored in the array CURRSTEMP; the gain ap- 
plied is x2. This code could be used for paper factory roller temperature readings in 
the process control example discussed in Chapter 1 if it were expanded to include 32 
identical rollers. 
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/* EXAMPLE OF SEQUENTIAL CHANNEL INPUT, SINGLE GAIN */ 



/* REQUEST MESSAGE*/ 

DECLARE SQS$INP$MSG STRUCTURE 

(LINK ADDRESS, 

LENGTH ADDRESS, 

TYPE BYTE, 

HOME$EXCHANGE ADDRESS, 

RESPONSESEXCHANGE ADDRESS, 

STATUS ADDRESS, 

BASE$REG$POINTER ADDRESS, 

CHAN$GAIN BYTE 

UNUSED BYTE 

DATA$ARRAY$POINTER ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS); 
/* ASSUMED CONTENT OF MESSAGES:*/ 
/* 0, 21, AISQS, 0,.RESP$EX, 0, 0R700H, 01000000B, 
0,.CURR$TEMP,32,0*/ 



/* EXCHANGE DEFINITION */ 

DECLARE EXCHANGESDESCRIPTOR LITERALLY 'STRUCTURE 

(MESSAGESHEAD ADDRESS, 

MESSAGESTAIL ADDRESS, 

TASK$HEAD ADDRESS, 

TASK$TAIL ADDRESS, 

EXCHANGE$LINK ADDRESS)'; 

/* ANALOG HANDLER AND RESPONSE EXCHANGES */ 
DECLARE RQAIEX EXCHANGESDESCRIPTOR EXTERNAL; 
DECLARE RESPSEX EXCHANGE$DESCRIP"OR; 

/'DATA ARRAY*/ 

DECLARE CURR$TEMP(32) ADDRESS; 



/* POINTER TO RETURN MESSAGE*/ 
DECLARE T1 ADDRESS; 

/* EXTERNAL PROCEDURES */ 
RQCXCH: PROCEDURE (X) EXTERNAL; 

DECLARE X ADDRESS; • 
END RQCXCH; 

RQSEND: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQSEND; 

RQWAIT: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQWAIT; 

/* BUILD RESPONSE EXCHANGE */ 
CALL RQCXCH(.RESP$EX); 

/* SEND INPUT REQUEST, WAIT FOR RESPONSE */ 
CALL RQSEND(. RQAIEX, .SQS$INP$MSG); 
T1 = RQWAIT(.RESP$EX,0); 

/* USER ERROR CHECKING ROUTINE GOES HERE */ 
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Sequential Channel Input with Variable Gain. 



Request Message Format. A task requesting that a sequence of consecutive chan- 
nels be sampled, with a different gain applied to each sample, creates and sends (to 
RQAIEX) a message with the format shown in figure 8-4. Asterisks denote fields 
that must be coded by the user task before the message is sent. Shaded fields are 
those set or changed by the Analog Input Handler when it returns the message. 



LINK 

2 LENGTH* 

4 TYPE* | 

5 HOME EXCHANGE 

7 RESPONSE EXCHANGE* 

9 STATUS 

11 BASE 1EG POINTER* 

13 CHAN-GAIN ARRAY POINTER* 

15 DATA ARRAY POINTER* 

17 COUNT* 



19 actual : -., 

Figure 8-4. Request Message for Sequential Channel Input 
with Variable Gain 



LENGTH is 21. 
TYPE isAISQV (32). 

HOME EXCHANGE is not used by the Analog Input Handler. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange to 
which the Analog Input Handler is to send the message when the operation is com- 
pleted. 

When the Analog Input Handler returns this message, STATUS is set to 1, 2, 3, or 4, 

to indicate one of the following conditions: 

1: all data collected. 

2: (reserved for future use.) 

3: operation aborted; converter did not respond. 

4: (reserved for future use.) 

BASE REG POINTER must specify the address of the Command-Status Register of 
the selected A/D converter. 

CHAN-GAIN ARRAY POINTER must specify the address of the array giving the 
input voltage gain to be applied to each sample. The gain in the i tn position of this 
array (recall that the i th element of the array has array index i-1) is applied to the i th 
channel in the sequence. The first element in the array also specifies the channel 
number of the first channel in the sequence. The number of elements in the array is 
equal to COUNT, and each element is a byte formatted as follows: 

7 6 5 4 

| GAIN | [""CHANNEL NO. | 

CHANNEL NO., bits 0-4: channel number of the first sample; a number 0-31 . 
Required only for the first element in the array, and must be set to zero in the 
remaining elements. 
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GAIN, bits 6-7: gain to be applied to the ith sample; a value of 0, 1, 2, or 3; 
represents a gain of xl, x2, x4, or x8, respectively. 
Bit 5 is ignored. 

DATA ARRAY POINTER must specify the address of the array to receive the 
sampled inputs. The number of elements in the array is equal to COUNT, and 
each element is two bytes. The Analog Input Handler will store the i tn sample 
in the i tn element of the array, in the following format: 



| o o o o 1 



Each element represents the actual value read from the A/D converter Data Register 
— 12 bits of data, followed by 4 zeros in the least significant bit positions. The 
voltage level corresponding to the 12-bit number is dependent upon the full-scale 
voltage range and the binary code, both of which are jumper-selected by the user as 
described in the Hardware Reference Manual for the analog input board. (See list of 
manuals an the beginning of this chapter.) 

COUNT must specify the number of channels to be sampled. CHANNEL NO. plus 
COUNT must not exceed 32. 



When the Analog Input Handler returns this message, ACTUAL is set to the actual 
number of channels sampled. 



Example. The following coding example takes samplings from analog channels 30 
and 31 and stores the values in structure DAT A$ ARRAY. A gain of x8 is applied to 
the input from channel 30, and a gain of x2 is applied to the input from channel 31 . 
This code could be used to update both the roller pressure and roller temperature 
readings in the Chapter 1 process control example if these two operations were com- 
bined into one step. 



/* EXAMPLE OF SEQUENTIAL CHANNEL INPUT, VARIABLE GAIN */ 

/* REQUEST MESSAGE */ 

DECLARE SQV$INP$MSG STRUCTURE 

(LINK ADDRESS, 

LENGTH ADDRESS, 

TYPE 3YTE, 

HOMESEXCHANGE ADDRESS, 

RESPONSESEXCHANGE ADDRESS, 

STATUS ADDRESS, 

BASE$REG$POINTER ADDRESS, 

CHAN$GAIN$ARRAY$PTR ADDRESS, 

DATA$ARRAY$POINTER ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS); 
/* ASSUMED CONTENT OF MESSAGE: */ 
/* 0, 21, AISQV, 0,.RESP$EX, 0, 0F700H,.CG$ARRAY, 
.DATA$ARRAY, 2, */ 
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/* EXCHANGE DEFINITION */ 

DECLARE EXCHANGESDESCRIPTOR LITERALLY 'STRUCTURE 



/* ANALOG HANDLER AND RESPONSE EXCHANGES*/ 
DECLARE RQAIEX EXCHANGESDESCRIPTOR EXTERNAL; 
DECLARE RESPSEX EXCHANGESDESCRIPTOR; 



/'CHAN-GAIN ARRAY*/ 
DECLARE CGSARRAY (2) BYTE; 

/* ASSUMED CONTENTS: 1101111013, 01000000B */ 



/* DATA ARRAY (HERE DECLARED AS STRUCTURE IN ORDER 
* TO GIVE INDIVIDUAL NAMES TO ELEMENTS)*/ 
DECLARE DATASARRAY STRUCTURE 

(CURRSPRESS ADDRESS, 

CURRSTEMP ADDRESS); 



/* POINTER TO RETURN MESSAGE */ 
DECLARE T1 ADDRESS; 



/* EXTERNAL PROCEDURES * / 
RQCXCH: PROCEDURE (X) EXTERNAL; 

DECLARE X ADDRESS; 
END RQCXCH; 

RQSEND: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQSEND; 

RQWAIT: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQWAIT; 



/* BUILD RESPONSE EXCHANGE */ 
CALL RQCXCH(.RESPSEX); 



/* SEND INPUT REQUEST, WAIT FOR RESPONSE */ 
CALL RQSEND(. RQAIEX, .SQVSINPSMSG); 
T1 = RQWAIT(.RESP$EX, 0); 



/* USER ERROR CHECKING ROUTINE GOES HERE */ 
Random Channel Input. 

Request Message Format. A task requesting that a set of random channels be 
sampled creates and sends (to RQAIEX) a message with the format shown in figure 
8-5. Asterisks denote fields that must be coded by the user task before the message is 



(MESSAGESHEAD 

MESSAGESTAIL 

TASKSHEAD 



TASKSTAIL 
EXCHANGESLINK 



ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS)'; 
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sent. Shaded fields are those set or changed by the Analog Input Handler when it 
returns the message. 



LENGTH" 



HOME EXCHANGE 



RESPONSE EXCHANGE- 



BASE RE 3 POINTER- 



CHAN-GAIN A3RAY POINTER- 



DATA ARRAY POINTER- 



CCUNT- 



ACTUAL 



J 



Figure 8-5 . Request Message for Random Channel Input 



LENGTH is 21. 
TYPE is AIRAN (33). 

HOME EXCHANGE is not used by the Analog Input Handler. 

RESPONSE EXCHANGE must specify the address of the user-defined exchange to 
which the Analog Input Handler is to send the message when the operation is com- 
pleted. 

When the Analog Input Handler returns this message, STATUS is set to 1, 2, 3, or 4, 

to indicate one of the following conditions: 

1: all data collected. 

2: (reserved for future use.) 

3: operation aborted; converter did not respond. 

4: (reserved for future use.) 

BASE REG POINTER must specify the address of the Command-Status Register of 
the selected A/D converter. 

CHAN-GAIN ARRAY POINTER must specify the address of the array giving the 
channel number of each sample and the gain that is to be applied to it. The number 
of elements in the array is equal to COUNT, and each element is a byte formatted as 
follows: 

7 6 5 4 

| GAIN | [ CHANNEL NO- | 

CHANNEL NO., bits 0-4: channel number of the i tn sample; a number 0-31. 
GAIN, bits 6-7: gain to be applied to the i th sample; a value of 0, 1, 2, or 3; 
represents a gain of xl, x2, x4, or x8, respectively. 
Bit 5 is ignored. 

DATA ARRAY POINTER must specify the address of the array to receive the 
sampled inputs. The number of elements in the array is equal to COUNT, and 
each element is two bytes. The Analog Input Handler will store the i th sample 
in the i th element of the array, in the following format: 

15 4 3 

T DATA | | 
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Each element represents the actual value read from the A/D converter Data Register 
— 12 bits of data, followed by 4 zeros in the least significant bit positions. The 
voltage level corresponding to the 12-bit number is dependent upon the full-scale 
voltage range and the binary code, both of which are jumper-selected by the user as 
described in the Hardware Reference Manual for the analog input board. (See list of 
manuals at the beginning of this chapter.) 

COUNT must specify the number of channels to be sampled; the range is 1-254. 

When the Analog Input Handler returns this message, ACTUAL is set to the actual 
number of samples collected. 



Example. The following coding example is identical to the example given just 
previously (for sequential channel input with variable gain), except that the channels 
now being sampled are and 31 . 



/* EXAMPLE OF RANDOM CHANNEL INPUT, VARIABLE GAIN */ 

/* REQUEST MESSAGE */ 

DECLARE RAN$INP$MSG STRUCTURE 

(LINK ADDRESS, 

LENGTH ADDRESS, 

TYPE BYTE, 

HOMESEXCHANGE ADDRESS, 

RESPONSE$EXCHANGE ADDRESS, 

STATUS ADDRESS, 

BASE$REG$POINTER ADDRESS, 

CHAN$GAIN$ARRAY$PTR ADDRESS, 

DATA$ARRAY$POINTER ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS); 
f ASSUMED CONTENT OF MESSAGES */ 
/* 0, 21, AIRAN, 0,.RESP$EX, 0, 0F700H,.CG$ARRAY, 
.DATA$ARRAY, 2, * / 

/* EXCHANGE DEFINITION */ 

DECLARE EXCHANGESDESCRIPTOR LITERALLY 'STRUCTURE 

(MESSAGE$HEAD ADDRESS, 

MESSAGESTAIL ADDRESS, 

TASKSHEAD ADDRESS, 

TASKSTAIL ADDRESS, 

EXCHANGESLINK ADDRESS)'; 

/* ANALOG HANDLER AND RESPONSE EXCHANGES */ 
DECLARE RQAIEX EXCHANGESDESCRIPTOR EXTERNAL; 
DECLARE RESPSEX EXCHANGESDESCRIPTOR; 

/•CHAN-GAIN ARRAY*/ 
DECLARE CGSARRAY (2) BYTE; 

/* ASSUMED CONTENTS: 11000000B, 01011111 B */ 

/* DATA ARRAY HERE DECLARED AS STRUCTURE IN ORDER 

TO GIVE INDIVIDUAL NAMES TO ELEMENTS */ 
DECLARE DATASARRAY STRUCTURE 

(CURRSPRESS ADDRESS, 

CURRSTEMP ADDRESS); 
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/* POINTER TO RETURN MESSAGE */ 
DECLARE T1 ADDRESS; 

/* EXTERNAL PROCEDURES */ 
RQCXCH: PROCEDURE (X) EXTERNAL; 

DECLARE X ADDRESS; 
END RQCXCH; 

RQSEND: PROCEDURE (X,Y) EXTERNA .; 

DECLARE (X,Y) ADDRESS; 
END RQSEND; 

RQWAIT: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQWAIT; 

/* BUILD RESPONSE EXCHANGE */ 
CALL RQCXCH(.RESPSEX); 

/* SEND INPUT REQUEST, WAIT FOR RESPONSE */ 
CALL RQSEND(.RQAIEX,.RAN$INP$MSG); 
T1 = RQWAIT(.RESP$EX, 0); 

/* USER ERROR CHECKING ROUTINE GOES HERE ' / 



Random Channel Output. 



Request Message Format. A task requesting random channel output creates and 
sends (to RQAOEX) a message with the format shown in figure 8-6. Asterisks 
denote fields that must be coded by the user task before the message is sent. Shaded 
fields are those set or changed by the Analog Input Handler when it returns the 
message. 






LIN K 


2 


LENGTH* 


4 


TYPE- 


5 


HOME EXCHANGE 


7 


RESPONSE E XCHANGE* 


9 


STA'US 


11 


BASE REG POINTER- 


13 


CHANNEL ARRAY POINTER- 


15 


DATA ARRAY POINTER- 


17 


COUNT- 



Figure 8-6. Request Message for Random Channel Output 



LENGTH is 19. 
TYPE is AORAN (38). 

HOME EXCHANGE is not used by the Analog Output Handler. 



RESPONSE EXCHANGE must specify the address of the user-defined exchange to 
which the Analog Input Handler is to send the message when the operation is com- 
pleted. 
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When the Analog Input Handler returns this message, STATUS is set to 1 or 2, 

to indicate one of the following conditions: 

1: all data output. 

2: (reserved for future use.) 

BASE REG POINTER must specify the address of the Holding Register for D/A 
Channel of the converter receiving the outputs. 

CHANNEL ARRAY POINTER must specify the address of the array giving the 
number of each channel to be set. The number of elements in the array is COUNT. 
Each element is a byte which may take on a value 0-3. 

DATA ARRAY POINTER must specify the address of the array giving the digital 
values to be applied to the channels indicated in CHANNEL ARRAY. The number 
of elements in the array is equal to COUNT, and each element is a two-byte value 
having the following format: 

15 4 3 

DATA I I 



Each element represents the value to be output to the D/A converter registers — 12 
bits of data, followed by 4 zeros in the least significant bit positions. The 12-bit 
number corresponding to a specific voltage level is dependent upon the full-scale 
voltage range and the binary code, both of which are jumper-selected by the user as 
described in the Hardware Reference Manual for the analog input board. (See list of 
manuals at the beginning of this chapter.) 

COUNT must specify the number of channels to be set; the range is 1-4. 



Example. The following coding example provides analog outputs on channels 2 and 
3, respectively. This code could be used to make pressure and temperature ad- 
justments in the process control example described in Chapter 1 . 



/* EXAMPLE OF RANDOM CHANNEL OUTPUT */ 

/* REQUEST MESSAGE */ 

DECLARE RAN$OUTP$MSG STRUCTURE 

(LINK ADDRESS, 
LENGTH ADDRESS, 
TYPE BYTE, 
HOMESEXCHANGE ADDRESS, 
RESPONSE$EXCHANGE ADDRESS, 
STATUS ADDRESS, 
BASE$REG$POINTER ADDRESS, 
CHAN$GAIN$ARRAY$PTR ADDRESS, 
DATA$ARRAY$POINTER ADDRESS, 
COUNT ADDRESS); 
1* ASSUMED CONTENT OF MESSAGES:*/ 
/* 0, 19, AORAN, 0,.OUT$RESP$EX, 0, 0F708H,.CH$ARRAY, 
.OUTSARRAY, 2*7 

/* EXCHANGE DEFINITION */ 

DECLARE EXCHANGESDESCRIPTOR LITERALLY 'STRUCTURE 

(MESSAGE$HEAD ADDRESS, 

M ESS AG E$TAI L ADDRESS, 

TASK$HEAD ADDRESS, 

TASKSTAIL ADDRESS, 

EXCHANGESLINK ADDRESS)'; 
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/* ANALOG HANDLER AND RESPONSE EXCHANGES */ 
DECLARE RQAOEX EXCHANGE$DESCRIPTOR EXTERNAL; 
DECLARE OUT$RESP$EX EXCHANGE$DESCRIPTOR; 

/"CHANNEL ARRAY*/ 
DECLARE CHSARRAY (2) BYTE; 

/* ASSUMED CONTENTS: 2, 3*/ 

/* DATA ARRAY HERE DECLARED AS STRUCTURE IN ORDER 
TO GIVE INDIVIDUAL NAMES TO ELEMENTS */ 
DECLARE OUTSARRAY STRUCTURE 

(CORRECTSPRESS ADDRESS, 

CORRECTSTEMP ADDRESS); 

I' POINTER TO RETURN MESSAGE */ 
DECLARE T1 ADDRESS; 

/* EXTERNAL PROCEDURES */ 
RQCXCH: PROCEDURE (X) EXTERNAL; 

DECLARE X ADDRESS; 
END RQCXCH; 

RQSEND: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQSEND; 

RQWAIT: PROCEDURE (X,Y) EXTERNAL; 

DECLARE (X,Y) ADDRESS; 
END RQWAIT; 

/* BUILD RESPONSE EXCHANGE */ 
CALL RQCXCH(.OUT$RESP$EX); 

/* SEND OUTPUT REQUEST, WAIT FOR RESPONSE */ 
CALL RQSEND(. RQAOEX,. RAN$OUTP$MSG); 
T1 = RQWAIT(.OUT$RESP$EX,0); 

/* USER ERROR CHECKING ROUTINE GOES HERE */ 




CHAPTER 9 
BOOTSTRAP LOADER 



The iRMX 80 Bootstrap Loader adds considerable flexibility to iRMX 80 systems 
which are equipped with disk, by allowing you to store much of your application 
software on disk rather than in ROM. This is advantageous because 

• disk-resident software is easier anc less expensive to modify than PROM- 
resident software. 

• you can use the same hardware for multiple iRMX 80-based application systems. 

The Bootstrap Loader can be used for true bootstrap loading, where a minimal 
iRMX 80-based system loads into RAM :he balance of an application system, which 
then runs as if it had been in ROM all along. In addition, the Bootstrap Loader can 
be used to load additions, as they are needed, or even replacements, to a running 
application system. We refer to these two uses of the Bootstrap Loader as bootstrap 
loading and program-controlled loading. We refer to the system containing the 
Bootstrap Loader as the loader system, while the file that it loads is a loadable file. 



The Bootstrap Loader is designed for use with iSBC 80/ 10, 80/20, 80/24, and 80/30 
single board computers running in conjunction with an iSBC disk controller board 
and disk drive. Memory requirements include at least 4K bytes of PROM (for the 
minimal system), sufficient RAM for the system or systems to be loaded, and an 
additional 1000 bytes of RAM (of which 336 bytes must be controller-addressable) 
for use by the Bootstrap Loader. 

In addition to the Nucleus, the Bootstrap Loader's software requirements include the 
DISK.IO service of the Disk File System and the related controller software. 

All loading, whether bootstrap or program-controlled, is done from the first device 
you specify when configuring with the Interactive Configuration Utility. 



Bootstrap Loading 

With the minimal iRMX 80 system (Nucleus, Bootstrap Loader, and DISKFO) in 
ROM, and the file that is to be loaded in the proper disk drive, you initiate bootstrap 
loading by supplying power to the CPU board or, if the power is already on, by 
sending a RESET signal to the CPU board The Bootstrap Loader knows what file to 
load because you supplied the file name when configuring with the Interactive 
Configuration Utility. After the loading operation is completed, the Bootstrap 
Loader merges the added code with the minimal system, creating an enlarged iRMX 
80 application system. When this is done, the enlarged system begins to run. 

Program-Controlled Loading 

Only an iRMX 80 system which has been bootstrap loaded can perform program- 
controlled loading. 

When the Bootstrap Loader is invoked under program control, one of three things 
occurs, depending upon the nature of the invocation: 

a. The Bootstrap Loader loads the loadable file specified during configuration with 
the ICU80 utility. The whole system is initialized; in particular, the tasks and 
exchanges are initialized and then made ready. In this way, the Bootstrap Loader 



Use Environment 



Bootstrap Loader 



RMX/80 



system and the loadable file are merged to form a single system. 

b. The Bootstrap Loader loads the loadable file that is specified by the currently 
executing system. The whole system is initialized; in particular, the tasks and 
exchanges are initialized and then made ready. Again, the Bootstrap Loader 
system and the loadable file are merged to form a single system. However, in this 
case, the invoking system is effectively deleted. 

c. The loadable file is appended to the current system. The new tasks and 
exchanges are initialized and become merged with the current system. This type 
of loading can be used for performing overlays, provided that, before invoking 
the Bootstrap Loader, the current system deletes the tasks and exchanges that 
are no longer needed. 

In order to cause loading of the type a, all that is required is a jump to location 0, a 
reset, or an RST instruction. 

Loading of type b can be accomplished in two ways. One way is to jump to the 
location RQSTRT after setting the variable RQNAME equal to the address of the 
name of the file to be loaded. The name must be stored in a nine byte area of 
memory, with the filename portion left-justified in the first six bytes and the 
extension portion left-justified in the last three bytes. Unused bytes must be filled 
with ASCII nulls (OH). For example, the file name FILE.A would be stored as 
FILE00A00. RQNAME is a two-byte, PUBLIC iRMX 80 variable, and RQSTRT is 
a PUBLIC label. 

The other way of accomplishing the type b loading involves a message/ exchange 
interface. After assigning the address of the the file name to RQNAME, as described 
in the previous paragraph: 

1. Do an RQWAIT or RQACPT at the exchange RQBOTX. The Bootstrap 
Loader will have sent a message to that exchange, so there should not ordinarily 
be any delay in receiving the message. 

2. Assign the value 40 to the TYPE field of the message. 

3. Send the modified message to the RQLODX exchange. RQLODX is declared in 
iRMX 80 as a PUBLIC exchange. 

Type c loading is done using exactly the same message/ exchange interface, except 
that the value 41 must be assigned to the TYPE field. 

Information for ICU80 Users 

The loader system is a complete iRMX 80 system and therefore must be configured 
with the ICU80 utility. The loadable file, however, must be configured only if it 
contains executable code. Therefore, when you have a loadable file with code, you 
must separately configure the loader system and the loadable file. The manner in 
which you configure one of these influences the manner in which you configure the 
other, according to the following rules: 

• All of the interrupt exchanges and disk controllers for both the loader system 
and the loadable file must be configured as part of the loader system. Neither 
interrupt exchanges nor disk controllers may be configured as part of the 
loadable file. 

• The loader system must include the DISKIO service of the Disk File System, and 
must be configured to include controller-addressable memory ("CAM ADR:" 
prompts for this). If the loadable file requires DFS services that are not 
configured into the loader system, then these services must be configured into the 
loadable file. 

• When configuring the loader system and the loadable file, you should ensure that 
only one of them contains DFS directory services. 
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• The loadable file must be configured with controller-addressable memory (the 
"CAM ADR:" prompt) if either it is configured for n files or it has its own 
buffers for disk I/O. 

• Respond to the "LOADABLE:" prompt with "no" when configuring the loader 
system, and respond with "yes" when configuring the loadable file. 

If your loadable file contains only data, do not attempt to configure it. Instead, 
assuming that your file is named YOUR. DAT, use the following link and locate 
statements to prepare the file for loading: 

LINK LOADED. LIB(DUMINI), YOUR. DAT TO YOUR.LNK 

LOCATE YOUR.LNK TO YOUR.LOC 

The file is now loadable under the name YOUR.LOC. 



CHAPTER 10 
COMMAND LINE INTERPRETER 



General Description 

The iRMX 80 Command Line Interpreter (CLI) enables an operator at a terminal to 
start up various tasks by entering commands (command lines). The iRMX 80 
Executive provides some of those tasks, while developers of iRMX 80-based 
application systems can supply others to meet their special needs. 

A command line consists of a key word followed optionally by a string of characters. 
When an operator enters a command line, the CLI strips off the identifying key word, 
builds a message, and sends the message (w.th the address of the string, if any) to the 
exchange that it knows is associated with the key word. A task, whose purpose is to 
respond to messages sent to that exchange, receives the message and performs the 
appropriate action. When done, the task returns the message to the indicated 
response exchange, thereby informing the waiting CLI that the task is finished. 

Use Environment 

The Command Line Interpreter's terminal requires the support of an input/ output 
Terminal Handler. In systems using the CLI, all input through the Terminal Handler 
is directed to the CLI, so the input side of the Terminal Handler is fully dedicated to 
the CLI. If you need to use the input portion of the Terminal Handler for other 
purposes, it will be necessary first to suspend the task whose descriptor is named 
RQCLID. Then, if you want to use the CLI again, you can do so after resuming the 
task. 

Memory and Hardware Requirements 

The Command Line Interpreter requires less than 31 25 bytes of code space and less 
than 225 bytes of data space; it uses no more than 300 bytes of stack. Refer to 
Appendix D for exact byte counts. 

Invoking the Command Line Interpreter 

If the Command Line Interpreter is included in a configuration, it "comes up" when 
the system is initiated and displays the message 

RMX 80 CLI Vx.x 

It then issues its prompt ">". 

CLI Commands 

For a command to be interpreted correctly by the CLI, it must consist of the 
command name (this is the key word), followed optionally by a "command tail". The 
command name can be any string of from one to six ASCII characters (blanks and 
carriage returns not allowed); if a longer name is entered, the CLI displays the 
message 

<command-name>, COMMAND TOO LONG 

After the command name there must be a blank or a carriage return. If a blank is 
used, the command tail can be any string of from zero to 115 ASCII characters 
(carriage returns not allowed), followed by a carriage return. 
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The Command Table 

The Command Line Interpreter maintains a table of command-name/ exchange 
pairs. After obtaining the command name from a command line, the CLI searches its 
command table from the beginning, looking for an entry which begins with the 
command name entered. If it finds such an entry, it sends the appropriate message 
(see the next section) to the exchange which is associated with the name it found in 
the table. If it does not find such an entry, it displays the message 

<command-name>, COMMAND NOT RECOGNIZED 

Because of the way the CLI searches its table, it is possible for the operator to enter 
an abbreviation of the intended command name. For example, suppose that a 
command table contains, in order, the following command names: 

DIRECT 

COPY 

FORMAT 

COMM1 

COMM2 

If the operator enters "C", "CO", "COP", or "COPY", the CLI will interpret the 
command name to be COPY. Entries of "COM", "COMM", or "COMMl" will be 
interpreted as COMMl. The only string that will be interpreted as COMM2 is 
"COM M2". 

NOTE 

You should use discretion in the way that you abbreviate command 
names in command lines. By abbreviating a name you run the risk of 
activating a task other than the one intended. If you are not sure what 
command names are in the command table, you can respond to the CLI 
prompt with a question mark followed by a carriage return; the CLI will 
then display the command names; in its table, in the order in which it 
searches through them. 

Command Line Interpreter Messages 

The messages sent by the Command Line Interpreter have the format shown in 
Figure 10-I. 






LINK 


2 


LENGTH 


4 


TYPE 


5 


HOME EXCHANGE 


7 


RESPONSE EXCHANGE 


9 


COUNT 


11 


BUFFER ADDRESS 



Figure 10-1. Command Line Interpreter Message 



LINK is an ADDRESS used by the Nucleus to enter messages in message queues 
at exchanges. 

LENGTH is a WORD containing the value 13. 

TYPE is a BYTE containing the value CLISMSGSTYPE = 8. 
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HOME EXCHANGE is an ADDRESS that is not set or used by the Command 
Line Interpreter. 

RESPONSE EXCHANGE is an ADDRESS containing the address of the 
exchange where this message must be returned after the current command line 
has been processed. 

COUNT is a WORD containing the number of bytes comprising the command 
tail. 

BUFFER ADDRESS is an ADDRESS containing the address of the command 
tail for the current command line. If BUFFER ADDRESS is zero, there is no 
command tail. 

Command Line Utilities Provided 
With the Command Line Interpreter 

When the Command Line Interpreter is activated, its command table contains the 
command-name/ exchange pairs that you specified when configuring with the 
Interactive Configuration Utility. In addition, the table can contain, depending on 
what you specified when configuring, command-name/ exchange pairs for any or all 
of three Intel-supplied ISIS-like utilities: DIRECTORY, COPY, and FORMAT. 

The DIRECTORY Utility 

The DIRECTORY utility displays the contents of a specified disk's directory. The 
command table entry for the DIRECTORY utility has the command name 
"DIRECT". A DIRECTORY command line must have the following syntax: 

D[IRECT]<device> 

where <device> is the name of the device containing the disk whose directory is to be 
displayed. If there is no <device> in a command line, or if the CLI cannot match the 
device name with an entry in its table, the CLI displays the message 

INVALID DEVICE NAME 



The FORMAT Utility 

The FORMAT utility initializes a new single- or double-density diskette or 
reinitializes an old diskette for reuse. The command-name/ exchange entry in the 
command table has the command name "FORMAT". A FORMAT command line 
must have the following syntax: 

F[ORMAT]<deviceXlabel> 

<device> specifies the drive containing the diskette to be formatted. <label> is the 
name to be given to the diskette. The syntax of <label> is the same as that for 
filenames, with up to six characters for name, a period, and up to three characters for 
extension. 



The COPY Utility 

The COPY utility copies a file or files from one location to another. The source and 
destination can each be either disk files or physical devices. The source location must 
be on an input device and the destination location must be on an output device. For 
example, a line printer can be a destination but cannot be a source. 

If the source or destination is on a diskette, the file name must be specified. If 
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multiple files are to be copied by means of a single COPY command line, it is 
sometimes convenient to use the "*" and "?" wild card symbols. The "*" symbol 
stands for all strings of characters, while the "?" symbol stands for any single 
character. For example, the specification FILE.* refers to all file names whose 
filename portion is FILE; this would include the file names FILE. EXT, FILE. EX, 
FILE.E, and FILE. On the other hand, FILE.E? refers to those file names whose 
filename portion is FILE and whose extension is two characters long and starts with 
"E"; this would include FILE. EX but not FILE.E or FILE. EXT. If you need to refer 
to all files on a disk device, you can specify this with the designation *.*. 

The syntax of COPY command lines is as follows: 

C[OPY] <sfile1>[,<sfile2> <sfi!en>] TO <dfile>[<switches>] 

where "sfile" stands for source file and "dfile" stands for destination file. The switches 
are described near the end of this section on the COPY command. 

If the devicename portion of a file name is omitted, the utility assumes the first device 
name supplied during configuration. If the filename/ extension portion of the 
destination file name is omitted, the utility assumes the same filename/ extension as 
was used in the source file specification. 

If the destination file does not already exist, it is created with all attributes set to 
"off", and the COPY operation is performed. If the destination file does exist, 
however, a message reading 

<dfile> ALREADY EXISTS. DELETE? (Y/N) 

is displayed on the screen. Any response starting with "Y" causes the existing <dfile> 
to be deleted, a new one to be created with its attributes set to "off", and the COPY to 
be performed. All other responses cancel the COPY request. 

If the destination file is write protected, the message 

<dfile> WRITE PROTECTED 

is displayed on the screen and the operation is cancelled. If the device specified in 
destination file specification is for input only, the message 

ERROR, AN INPUT FILE MAY NOT BE THE OUTPUT FILE 

is displayed on the screen. 

If more than one source file is specified, but only one destination file, the source files 
are copied and concatenated in the destination file, in the order in which they were 
listed in the command line. 

After each source file is copied, the message 

COPIED <sfile> TO <dfile> 

is displayed on the screen. In the case of concatenation, after each file is copied, the 
message 

APPENDED <sfile> TO <dfile> 
is displayed instead. 

When using wild cards, be sure that they are used in the same way in the 
specifications of <sfile> and <dfile>. For example, 

COPY :R2:ABC* TO :F1 :DEF* 

and 

COPY :R2:A?C TO :F1:D?F 
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are both valid. In the first case, all source files whose names begin with ABC are 
copied to the corresponding destination files whose names begin with DEF, that is, 
source file ABCS would be copied to destination file DEFS, and source file 
ABCXYZ would be copied to destination file DEFXYZ. The same rule applies in the 
second case. The following command lines are invalid because the occurrences of the 
wild cards do not match: 

COPY :R2:ABC* TO :F1:DEF 

and 

COPY :R2:A?? TO :F1:DE? 

If wild cards are used inconsistently between the source and destination file names, 
the message 

ERROR, WILD CARDS DO NOT MATCH 

is displayed on the screen. If you try to use wild cards with more than one source file 
name, that is, to do concatenation, the message 

WILD CARDS MAY NOT BE USED DURING CONCATENATE 

is displayed on the screen. 

Some of the standard effects of COPY command tails can be overridden by means of 
"switches" that are placed at the end of command tails. The switches available to 
users of the COPY utility are the following: 

B Brief. If the destination file already exists, the message "<dfile> ALREADY 
EXISTS. DELETE? ( Y/ N)" is suppressed, and the destination file is deleted and 
recreated with the data from the source file(s). This switch is ignored if the U 
switch is also present. 

C Copy attributes. The destination file is created with the same attributes (except 
for the format(F) attribute) as those of the source file. 

P Pause. This switch allows you to copy between two diskettes on the same drive. 
The COPY command prompts you by issuing the following messages: 

LOAD SOURCE DISKETTE AND TYPE (CR) 
LOAD OUTPUT DISKETTE AND TYPE (CR) 

Q Query. This switch causes the message 

COPY <sfile> TO <dfile>? 

to be displayed on the screen before each copy operation. Any response starting 
with "Y" causes the operation to be performed. Any other response cancels the 
operation. 

U Update. If the destination file already exists, the message "<dfile> ALREADY 
EXISTS. DELETE? (Y/N)" is suppressed, and the destination file is 
overwritten. The destination file is opened for updating instead of being deleted. 
The length is not changed unless the operation causes an increase in the size of 
the file. The new file has all attributes unchanged unless the C switch is present, 
in which case the attributes of the source file are added to the attributes already 
set for the destination file. 

Example I. This example copies three files to one, overwriting its contents. 

>COPY CHAP1,CHAP2,CHAP3 TO BOOK 
:F0:BOOK FILE ALREADY EXISTS. DELETE? (Y/N)Y 
APPENDED :F0:CHAP1 TO :F0:BOOK 
APPENDED :F0:CHAP2 TO :F0:BOOK 
APPENDED :F0:CHAP3 TO :F0:BOOK 
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Example 2. This example accomplishes the same thing as does example 1. 

>COPY CHAP1,CHAP2,CHAP3 TO BOOK U 
APPENDED :F0:CHAP1 TO :F0:BOOK 
APPENDED :F0:CHAP2 TO :F0:BOOK 
APPENDED :F0:CHAP3 TO :F0:BOOK 

Example 3. This example lists a file on the line printer. 

>COPY BOOK TO :LP: 
COPIED :F0:BOOK TO :LP: 

Example 4. This example lists some invalid COPY command lines and the responses 
they evoke from the COPY utility. 

>COPY MANY* TO ONE 

ERROR, WILD CARDS DO NOT MATCH 

>COPY SOME*, MORE* TO MANY* 

WILD CARDS MAY NOT BE USED DURING CONCATENATE 
>COPY :LP: TO DFILE 

ERROR, AN INPUT FILE MAY NOT BE AN OUTPUT FILE 

Information for ICU80 Users 

The Command Line Interpreter requires the use of the full or minimal input/ output 
Terminal Handler, or a user-written terminal handler. 

The DIRECTORY utility requires the Command Line Interpreter and the Disk File 
System services OPEN, CLOSE, and READ. 

The FORMAT utility requires the Command Line Interpreter and the Disk File 
System service FORMAT. 

The COPY utility requires the Command Line Interpreter and the Disk File System 
services OPEN, CLOSE, READ, WRITE, SEEK, ATTRIB, and DELETE. 
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APPENDIX A 


RMX/80 D 


ISKETTE FILES 



This appendix provides a list of the major files supplied on the iRMX 80 product 
diskettes, with a brief description of the contents of each file listed. The files are 
grouped here according to diskette (Nucleus, Extensions, or Configuration), then, 
within each group, according to type of file. 

Nucleus Diskette 

The following files reside on the iRMX 80 Nucleus diskette. These are all of the files 
required by the Nucleus. 

Relocatable Object Code Files 



RMXMIN.LIB Modules containing portions of the Nucleus for use with 

RMXOPT.LIB the iSBC 80/20, 8C/24, and 80/30 single board computers. 
RMXDBG.LIB Together, these libraries contain all of the Nucleus. You 
need not worry about how the Nucleus is divided into 
these libraries, because the SUBMIT file produced by 
the Interactive Configuration Utility automatically 
selects the modules that your application actually needs 
and links them together with your application code. 

Modules containing portions of the Nucleus for use with 
the iSBC 80/10 single board computers. Together, these 
libraries contain all of the Nucleus. You need not worry 
about how the Nucleus is divided into these libraries, 
because the SUBMIT file produced by the Interactive 
Configuration Utility automatically selects the modules 
that your application actually needs and links them 
together with your application code. 

Modules containing portions of the Nucleus for use with 
the iSBC 569 single board computers. Together, these 
libraries contain all of the Nucleus. You need not worry 
about how the Nucleus is divided into these libraries, 
because the SUBMIT file produced by the Interactive 
Configuration Utility automatically selects the modules 
that your application actually needs and links them 
together with your application code. 

Modules containing portions of the Nucleus for use with 
the iSBC 544 single board computers. Together, these 
libraries contain all of the Nucleus. You need not worry 
about how the Nucleus is divided into these libraries, 
because the SUBMIT file produced by the Interactive 
Configuration Utility automatically selects the modules 
that your applicat on actually needs and links them 
together with your application code. 

PL/M support procedures required by the iRMX 80 
Nucleus and extensions. 



810MIN.LIB 
810OPT.LIB 
810DBG.LIB 



544MIN.LIB 
5440PT.LIB 
544DBG.LIB 



569MIN.LIB 
5690PT.LIB 
69DBG.LIB 



5 



PLM80.LIB 
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PL/M INCLUDE Files 

The PL/M source code files listed in this section are useful when writing calls to 
iRMX 80 in PL/ M. To include any of these sections of code in your program, you 
need not write out the code — simply provide the name of the appropriate file in a 
PL/M SINCLUDE command. 

The following files contain PL/M declarations of various iRMX 80 data structure 
formats and related symbolic constants. The most-used of these files are printed here 
for your convenience. 



8020.ELT Declarations of various symbolic values relating to iSBC 

80/20 single boa'd computers. Most of these values are 
not needed by iRMX 80 users, particularly in applications 
containing the Terminal Handler. The values are 
provided for reference and for possible user extensions, 
such as the use of counter 1 of the 8253 Programmable 
Interval Timer. 



8030. ELT Declarations of various symbolic values relating to iSBC 

80/24 and 80/30 single board computers. Most of these 
values are not needed by iRMX 80 users, particularly in 
applications containing the Terminal Handler. The 
values are provided for reference and for possible user 
extensions, such as the use of counter 1 of the 8253 
Programmable Interval Timer. 



8010. ELT Declarations of symbolic values associated with the 8251 

Programmable Communications Interface (USART) to 
assist the user in any custom software in which the 
USART plays a part. 



SBC544.ELT Declarations of various symbolic values relating to iSBC 

544 single board computers. Most of these values are not 
needed by iRMX 80 users, particularly in applications 
containing the Terminal Handler. The values are 
provided for reference and for possible user extensions, 
such as the use of counter 1 of the 8253 Programmable 
Interval Timer. 



SBC569.ELT Declarations of various symbolic values relating to iSBC 

569 single board computers. Most of these values are not 
needed by iRMX 80 users, particularly in applications 
containing the Terminal Handler. The values are 
provided for reference and for possible user extensions, 
such as the use of counter 1 of the 8253 Programmable 
Interval Timer. 



INTRPT.ELT Declarations of symbolic values for the 8085 on-chip 

interrupts TRAP, A$LEV, B$LEV, and C$LEV. 



MSGTYP.ELT Declarations of iRMX 80-defined message types. 
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STATIC. ELT Declaration of Static Task Descriptor. 



DECLARE STATIC$TASK$DESCRIPTOR LITERALLY 'STRUCTURE ( 

NAME(6) BYTE, 

PC ADDRESS, 

SP ADDRESS, 

STKLEN ADDRESS, 

PRIORITY BYTE, 

EXCHANGE$ADDRESS ADDRESS, 

TASK$PTR ADDRESS)'; 

DECLARE CREATE$TABLE LITERALLY 'STRUCTURE ( 

TASK$POINTER ADDRESS, 

TASK$COUNT BY"E, 

EXCHANGE$PO INTER ADDRESS, 

EXCHANGE$COUNT BYTE)'; 



TASK. ELT Declaration of Task Descriptor 



DECLARE TASK$DESCRIPTOR LITERALLY 'STRUCTURE ( 
DELAY$LINK$FORWARD ADDRESS, 
DELAY$LINK$BACK ADDRESS, 
THREAD ADDRESS, 
DELAY ADDRESS, 
EXCHANGE$ADDRESS ADDRESS, 
SP ADDRESS, 
MARKER ADDRESS, 
PRIORITY BYTE, 
STATUS BYTE, 
NAME$PTR ADDRESS, 
TASK$LINK ADDRESS)'; 

DECLARE BOTTOM$FLAG LITERALLY '0C7C7H', 
UNUSED$FLAG LITERALLY 'OC 'H'; 

DECLARE TD$DELAY$LINK$FORWARD$OFFSET LITERALLY '0'; 

DECLARE TD$THREAD$OFFSET LITERALLY '4'; 

DECLARE TD$TASK$LINK$OFFSET LITERALLY '18'; 

DECLARE TASK$DESCRIPTOR$LENGTH L ITERALLY '20'; 



EXCH.ELT Declaration of Exchange Descriptor. 



DECLARE EXCHANGE$DESCRIPTOR LITERALLY 'STRUCTURE ( 

MESSAGE$HEAD ADDRESS, 

MESSAGE$TAIL ADDRESS, 

TASK$HEAD ADDRESS, 

TASK$TAIL ADDRESS, 

EXCHANGE$LINK ADDRESS)'; 
DECLARE ED$EXCHANGE$LINK$OFFSET LITERALLY '8'; 
DECLARE EXCHANGE$DESCRIPTOR$LENGTH LITERALLY '10'; 
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IED.ELT: 



Declaration of Interrupt Exchange Descriptor. 



DECLARE INT$EXCHANGE$DESCRIFTOR LITERALLY 'STRUCTURE ( 



MESSAGE$HEAD 

MESSAGE$TAIL 

TASK$HEAD 

TASK$TAIL 

EXCHANGE$LINK 

LINK 

LENGTH 

TYPE 



ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS, 
BYTE) 1 ; 



MSG.ELT: 



Declaration of message. 



DECLARE MSG$HDR LITERALLY ' 

LINK ADDRESS, 
LENGTH ADDRESS, 
TYPE BYTE, 
HOME$EXCHANGE ADDRESS, 
RESPONSE$EXCHANGE ADDRESS'; 

DECLARE MSG$DESCRIPTOR LITERALLY 'STRUCTURE ( 
MSG$HDR, 

REMAINDER(I) EIYTE)'; 
DECLARE MSG$LINK$OFFSET LITERALLY '0'; 
DECLARE MIN$MSG$LENGTH LITERALLY '5'; 



COMMON. ELT: 



Declara tions of common symbolic constants. 



DECLARE TRUE LITERALLY 'OFFH'; 
DECLARE FALSE LITERALLY '00H'; 
DECLARE BOOLEAN LITERALLY 'BYTE'; 
DECLARE FOREVER LITERALLY "WHILE V; 



The following files contain PL/ M declarations for iRMX 80 procedures and 
variables. 



SYNCH. EXT 

RQACPT.EXT 

RQISND.EXT 

INTRPT.EXT 

RQSETV.EXT 

RQENDI.EXT 

DLTASK.EXT 

DLEXCH.EXT 

OBJMAN.EXT 

RESUME. EXT 

SUSPND.EXT 

RDYLST.EXT 



Declarations of the RQSEND and RQWAIT procedures. 
Declaration of the RQACPT procedure. 
Declaration of the RQISND procedure. 
Declarations of the RQELVL and RQDLVL procedures. 
Declaration of the RQSETV procedure. 
Declaration of the RQENDI procedure. 
Declaration of the RQDTSK procedure. 
Declaration of the RQDXCH procedure. 
Declarations of the RQCTSK and RQCXCH procedures. 
Declaration of the RQRESM procedure. 
Declaration of the RQSUSP procedure. 
Declaration of the RQACTV variable. 
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Demonstration System Files 



The following files are provided to support the iRMX 80 Demonstration System, 
which is described in Appendix I. 



DEMO. LIB 

DEMOI 
DEM02 
DEM03 

DEMOI. CON 
DEM02.CON 
DEM03.CON 

LOAD1.CSD 
LOAD2.CSD 
LOAD3.CSD 
LOAD24.CSD 

CLI.PLM 
CLI.EXT 
GET.PLM 



SCANIN.PEX 

NUMOUT.PEX 

DBLANK.PEX 

DLIMIT.PEX 

SEQ.PEX 

SBC104.LIB 



SBC104.PLM 



Relocatable Object Modules for the Demonstartion 
Systems tasks. 

Absolute object code (LINKed and LOCATEd) for the 
iSBC 80/10, 80/20, and 80/24 and 80/30 versions, 
respectively, of the Demonstration System. 

Interative Configuration Utility dialogue for the iSBC 
80/10, 80/20, and 80/24 and 80/30 versions, respectively, 
of the Demonstration System. 

ISIS-II SUBMIT files used to load the iSBC 80/10, 80/20, 
80/30, and 80/24 versions, respectively, of the Demon- 
stration System with the ICE-80 or ICE-85 In-Circuit 
Emulator. 

PL/M source code for the Demonstration System 
Command Line Interpreter module. 

External declarations for the PUBLIC symbols provided 
by the Command Line Interpreter module. 

PL/M source code for the Demonstration System Free 
Space Manager Exerciser module, which contains the 
routines for the commands GET, PUT, POOL, and 
MESSAGE. 

External declaration of the utility procedure SCANIN. 

External declaration of the utility procedure NUMOUT. 

External declaration of the utility procedure DBLANK. 

External declaration of the utility procedure DLIMIT. 

External declaration of the utility procedure SEQ. 

Relocatable object modules provided for manipulating 
the clock hardware on the iSBC 104, 108, 116, and 517 
combination memory and I/O expansion boards. These 
modules are for the iSBC 80/10 version of the Demon- 
stration System. 

PL/M source code for the modules provided for manipu- 
lating the clock hardware on the iSBC 104, 108, 116, and 
517 combination memory and I/O expansion boards. 
These modules are for the iSBC 80/10 version of the 
Demonstration System. 



Extensions Diskette 

The following files reside on the iRMX 80 Extensions diskette. This diskette contains 
all files specific to the iRMX 80 extension;;. 



Relocatable Object Code Files 

THI810.LIB Modules for the input side of the full Terminal Handler 

for the iSBC 80/10 single board computers. 
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THI820.LIB 

THI830.LIB 

THO810.LIB 

THO820.LIB 

THO830.LIB 

MTHINP.LIB 

MTHOUT.LIB 

FREESP.LIB 
ADEBUG.LIB 
PDEBUG.LIB 
UNRSLV.LIB 

DFSDIR.LIB 
DFSEXT.LIB 

DIO.LIB 

DIO810.LIB 

DFSUNR.LIB 

AIHDLR.LIB 
AOHDLR.LIB 
BOOTLD.LIB 
BOTUNR.LIB 

LOADED. LIB 



Modules for the input side of the full Terminal Handler 
for the iSBC 80/20 single board computers. 

Modules for the input side of the full Terminal Handler 
for the iSBC 80/24 and 80/30 single board computers. 

Modules for the output side of the full Terminal Handler 
for the iSBC 80^10 single board computers. 

Modules for the output side of the full Terminal Handler 
for the iSBC 80/20 single board computers. 

Modules for the output side of the full Terminal Handler 
for the iSBC 80/24 and 80/30 single board computers. 

Modules for the input side of the minimal Terminal 
Handler. 

Modules for the output side of the minimal Terminal 
Handler. 

Modules for the Free Space Manager. 

Modules for active portion of the Free Space Manager. 

Modules for passive portion of the Free Space Manager. 

Declarations for resolving references to iRMX 80- 
defined public symbols not declared in the application 
code. 

Modules to implement the DFS directory structure. 

Modules to implement the Bad Block Format for ISIS-II 
compatibility on the iSBC 206 Disk Controller. 

Basic DFS I/O routines for the iSBC 80/20, 80/24, and 
80/30 single board computers. 

Basic DFS I/O routines for the iSBC 80/10 single board 
computer. 

Declarations for resolving references to DFS-defined 
public symbols not declared in the application code. 

Modules for the Analog Input Handler. 

Modules for the Analog Output Handler. 

Bootstrap Loader System modules. 

Declarations for resolving references to iRMX 80- 
defined PUBLIC symbols not declared in the applications 
code of a Bootstrap Loader System. 

Modules to be linked to systems loaded by the Bootstrap 
Loader System. 



PL/M INCLUDE Files 

The PL/M source code files listed in this section are useful when writing calls to 
iRMX 80 in PL/M. To include any of these sections of code in your program, you 
need not write out the code — simply provide the name of the appropriate file in a 
PL/M S1NCLUDE command. 
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The following files contain PL/M declarations of various iRMX 80 data structure 
formats and related symbolic constants. The most-used of these files are printed here 
for your convenience. 

THMSG.ELT Declaration of Terminal Handler read or write request 

message. 

DECLARE TH$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 
BUFFER$ADR ADDRESS, 
COUNT ADDRESS, 
ACTUAL ADDRESS, 
REMAINDER(128) BYTE)'; 
DECLARE MIN$TH$MSG$LENGTH LITERALLY '17'; 



CHAR.ELT 

DECLARE 



Declarations of various non-printable ASCII characters. 



NULL 


LITERALLY '00H', 


CONTROL$C 


LITERALLY '03H', 


CONTROL$E 


LITERALLY '05H', 


BELL 


LIBERALLY '07H', 


TAB 


LI""ERALLY '09H', 


LF 


LITERALLY 'OAH', 


VT 


LITERALLY 'OBH', 


FF 


LITERALLY 'OCH', 


CR 


LITERALLY 'ODH', 


CONTROL$P 


LITERALLY '10H', 


CONTROL$Q 


LITERALLY "I1H\ 


CONTROL$R 


LITERALLY '12H', 


CONTROL$S 


LITERALLY '13H', 


CONTROL$X 


LITERALLY '18H', 


CONTROL$Z 


LITERALLY '1AH', 


ESC 


LITERALLY '1BH', 


QUOTE 


LITERALLY '22H', 


LCA 


LITERALLY '61 H', 


LCZ 


LITERALLY '7AH', 


RUBOUT 


LITERALLY '7FH'; 



The following files contain PL/M declarations for iRMX 80 exchanges. 



FSMGR.EXT 


Declarations of the Free Space Manager allocation and 
reclamation exchanges. 


THDINI.EXT 


Declarations of the Terminal Handler input exchanges. 


THDINO.EXT 


Declarations of the Terminal Handler output exchanges. 


ATTRIB.EXT 


Declaration of RQATRX. 


DELETE. EXT 


Declaration of RQDELX. 


DIRECT.EXT 


Declaration of RQDIRX. 


DISKIO.EXT 


Declaration of RQDSKX. 


FORMAT.EXT 


Declaration of RQFMTX. 


LOAD. EXT 


Declaration of RQL.DX. 


OPEN.EXT 


Declaration of RQOPNX. 


RENAME. EXT 


Declaration of RQRNMX. 
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The following files contain definitions of various parameter values, declarations of 
general data structures, etc., that DFS users might find helpful. 



ATTRIB.ELT: 



Values for ATTRIB SWID parameter. 



DECLARE 



ATR$INV 
ATR$SYS 
ATR$WTP 
ATR$FMT 



LITERALLY '0', 
LTERALLY 1*. 
LITERALLY '2', 
LITERALLY '3'; 



DECLARE 



INVISIBLE$ATTRIBUTE 
SYSTEM $ATTR I BUTE 
WRITEP$ATTRIBUTE 
FORMAT$ATTRIBUTE 



LITERALLY '01 H', 
LITERALLY '02H', 
LITERALLY '04H\ 
LITERALLY '80H'; 



DEVCMD.ELT: 



Definition of IOINS values for DISKIO 
operations. 



DECLARE SEEK$COMMAND 

FORMAT$COMMAND 

RECALIBRATE 

READ$COMMAND 

VERIFY$COMMAND 

WRITE$COMMAND 

WRITE$DEL 

MOTOR$ON 

MOTOR$OFF 

RESERVED 



LITERALLY '1', 
LITERALLY '2', 
LITERALLY '3', 
LITERALLY '4', 
LITERALLY '5\ 
LITERALLY '6', 
LITERALLY T, 
LITERALLY '8', 
LITERALLY '9', 
LITERALLY '10'; 



DFSMSG.ELT: 



Declaration of DFS request messages. 



DECLARE ATTRIB$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

FILE$PTR ADDRESS, 

SWID ADiDRESS, 

VALUE ADDRESS)'; 

DECLARE CLOSE$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS)'; 

DECLARE DELETE$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

FILE$PTR ADDRESS)'; 



DECLARE DSK$REQ$MSG LITERALLY 'STRUCTURE ( 



MSGHDR, 




STATUS 


ADDRESS, 


DEVICE 


BYTE, 


IOINS 


ADDRESS, 


NSEC 


BYTE, 


TADR 


ADDRESS, 


SADR 


ADDRESS, 


BUFFER 


ADDRESS)'; 
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DECLARE FORMAT$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

FILEPTR ADDRESS)'; 

DECLARE LOAD$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

FILE$PTR ADDRESS, 

BIAS ADDRESS, 

ENTRY ADDRESS)'; 

DECLARE OPEN$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

FILE$PTR ADDRESS, 

ACCESS ADDRESS, 

AFR$XCH ADDRESS)'; 

DECLARE READ$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

BUFFER ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS)'; 

DECLARE RENAME$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

OLD$FILE$PTR ADDRESS, 

NEW$FILE$PTR ADDRESS)'; 

DECLARE SEEK$REQ$MSG LITERALLY 'STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

MODE ADDRESS, 

BLOCKNO ADDRESS, 

BYTENO ADDRESS)'; 

DECLARE WRITE$REQ$MSG LITERALLY STRUCTURE ( 
MSGHDR, 

STATUS ADDRESS, 

BUFFER ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS)'; 

FSREQ.ELT: Definition of DFS message types. 

DECLARE 

DFS$RD LITERALLY '8', 

DFS$WRT LITERALLY '12', 

DFS$SK LITERALLY '13', 

DFS$CLS LITERALLY '14', 

DFS$OPN LITERALLY '15', 

DFS$RNM LITERALLY '16', 

DFS$DEL LITERALLY '17', 

DFS$ATR LITERALLY '18', 

DFS$LD LITERALLY '19', 

DFS$FMT LITERALLY '20', 

DFS$DSK LITERALLY '21'; 
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FNB.ELT: 



Declaration of a File Name Block. 



DECLARE FILE$NAME$BLOCK LITERALLY 'STRUCTURE ( 
DEVICE$NAME(2) BYTE, 
FILE$NAME(6) BYTE, 
EXTENSIONS) BYTE)'; 



OPNACC.ELT: 



Values for OPEN ACCESS mode parameter. 



DECLARE RD$ACC 
WRT$ACC 
UPD$ACC 

DECLARE READ$ACCESS 
WRITE$ACCESS 
UPDATE$ACCESS 



LITERALLY T. 
LITERALLY '2', 
LITERALLY '3'; 

LITERALLY T, 
LITERALLY '2', 
LITERALLY '3'; 



SEEK.ELT: 



Values for SEEK MODE parameter. 



DECLARE 



SK$CUR 

SK$DECR 

SK$SET 

SK$INCR 

SK$EOF 



LITERALLY '0', 
LITERALLY T. 
LITERALLY '2', 
LITERALLY '3', 
LITERALLY '4'; 



The following files contain PL/M decla rations commonly needed by users of the 
Analog Handlers. The most-used of these files are printed here for your convenience. 



AIHPRC.EXT: 

AOHPRC.EXT: 

AIH.EXT: 

AOH.EXT: 

AIMSG.ELT: 



Declaration of the RQAIH procedure. 
Declaration of the RQAOH procedure. 
Declaration of the RQAIEX exchange. 
Declaration of the RQAOEX exchange. 
Declara:ion of analog input request message. 



DECLARE AIMSG LITERALLY 'STRUCTURE ( 



MSG$HDR, 

STATUS 

BASE$PTR 

CHANNEL$GAIN 

ARRAY$PTR 

COUNT 

ACTUAL$COUNT 



ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS, 
ADDRESS)'; 



AOMSG.ELT: 



Declaration of analog output request message. 



DECLARE AIREP 
AISQS 
AISQV 
AIRAN 



LITERALLY '30', 
LITERALLY '31', 
LITERALLY '32', 
LITERALLY '33'; 
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AITYP.ELT: Definition of analog input message types. 



DECLARE AOMSG LITERALLY 'STRUCTURE ( 
MSG$HDR, 

STATUS ADDRESS, 

BASE$PTR ADDRESS, 

ARRAY1$PTR ADDRESS, 

ARRAY2$PTR ADDRESS, 

COUNT ADDRESS)'; 

AOTYP.ELT: Definition of analog output message types. 



DECLARE AORAN LITERALLY '38'; 
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This appendix is a summary of the currently defined public and external symbols 
within the RMX/80 system. Public symbols are those that can be addressed from a 
user task. Each user task or module that addresses an RMX/80 public symbol must 
declare that symbol external. The user task or module that defines an RMX/80 
external symbol must declare it public. 

Publics Defined by RMX/80 



Procedures 




RQSEND: 


Send Message operation. 


RQWAIT: 


Wait for Message operation. 


RQACPT: 


Accept Message operation. 


RQCTCK: 


Clock Tick operation (iSBC 80/10 version only). 


RQCXCH: 


Create Exchange operation. 


RQCTSK: 


Create Task operation. 


RQDXCH: 


Delete Exchange operation. 


RQDTSK: 


Delete Task operation. 


RQSUSP: 


Suspend Task operation. 


RQRESM: 


Resume Task operation. 


RQDLVL: 


Disable Level operation. 


RQELVL: 


Enable Level operation. 


RQISND: 


Interrupt Send operation. 


RQENDI: 


End Interrupt operation. 


RQSETP: 


Set Poll operation (iSBC 80/10 version only). 


RQSETV: 


Set Vector operation. 


RQTIME: 


System time unit for 8253 P.I.T. 



Data Structures and Variables 

RQL1EX: Level 1 interrupt exchange. 

RQACTV: Address of Task Descriptor of running task. 

RQCTAB: Terminal Handler control character table. 

RQDBUG: Terminal Handler debug input exchange. 
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RQINPX: Terminal Handler input exchange. 

RQOUTX: Terminal Handler output exchange. 

RQALRM: Terminal Handler alarm output exchange. 

RQWAKE: Debugger wakeup exchange (declared in Terminal Handler). 

RQFS AX : Free Space Manager allocation exchange. 

RQFSRX: Free Space Manager reclamation exchange. 

RQFREE: Free Space Manager list of free (i.e., available) messages. 

RQATRX : Disk File System ATTRIB request exchange. 

RQDELX: Disk File System DELETE request exchange. 

RQDIRX: Disk File System directory services request exchange. 

RQDSKX: Disk File System DISKIO request exchange. 

RQFMTX: Disk File System FORMAT request exchange. 

RQLDX: Disk File System LOAD request exchange. 

RQOPNX: Disk File System OPEN request exchange. 

RQRNMX: Disk File System RENAME request exchange. 

RQAIEX: Analog Input Handler request exchange. 

RQAOEX: Analog Output Handler request exchange. 

RQNAME: Bootstrap Loader pointer to file name. 

RQRSTV: Bootstrap Loader RST interrupt vector array. 

RQBOTX: Bootstrap Loader token message exchange. 

RQLODX: Bootstrap Loader wakeup exchange. 

Tasks 

RQTHDI: Terminal Handler input task. 

RQTHDO: Terminal Handler output task. 

RQFMGR: Free Space Manager task. 

RQADBG: Active Debugger task. 

RQPDBG: Passive Debugger task. 

RQPATR: Disk File System ATTRIB task. 

RQPDEL: Disk File System DELETE task . 

RQPDIR: Disk File System directory services task. 
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RQPDSK: 


Disk File System D1SKIO task. 




D OTJO 1 ■ 
KvJrlLM. 


Disk File System controller handler task for iSBC 201 and 202 
controllers. 


RQHD4: 


Disk File System controller handler task for iSBC 204 
controllers. 




RQHD6: 


Disk File System controller handler task for iSBC 206 
controllers. 




RQPFMT: 


Disk File System FORMAT task. 




RQPLD: 


Disk File System LOAD task. 




RQPRNM: 


Disk File System RENAME task. 




P OHO IV- 


Disk File System interrupt polling routine for iSBC 201 and 202 
controllers (iSBC 80/ 10 version only). 


RQHD4V: 


Disk File System interrupt polling routine for iSBC 
controllers (iSBC 80/ 10 version only). 


204 


RQHD6V: 


Disk File System interrupt polling routine for iSBC 
controllers (iSBC 80/ 10 version only). 


206 


RQAIH: 


Analog Input Handler task. 




RQAOH: 


Analog Output Handler task. 




RQBOOT: 


Bootstrap Loader task. 
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This appendix is a summary of the message types currently defined by RMX/80. The 
following codes appear in the TYPE field of the message heading — either provided 
there by a user task before sending the message to an RMX/80 extension task, or 
supplied by RMX/80 when it sends the message. For details on particular message 
types, refer to Chapter 2 and to the chapters on the various RMX/80 extensions. 



The PL/M symbolic names listed below for the type codes are supplied in the IN- 
CLUDE files MSGTYP.ELT, DFSREQ.ELT, AITYP.ELT, and AOTYP.ELT. 
PL/M programmers should INCLUDE these files in their programs and use the 
symbolic names for messages types. Assembly language programmers must code 
the numeric values. 

Type codes through 63 are reserved for RMX/80 use, although not all of these 
codes are currently defined. Types 64 through 255 are available to be defined by the 
user. 

TYPE CODE DEFINITION 



DATASTYPE = 0: Message containing data of no specific type. 

INT$TYPE = 1: Message generated by RMX/80 as the result of 

an interrupt at the level associated with the ex- 
change from which the message was obtained. A 
message of this type is read-only and has a 
LENGTH of 5. 



MISSED$INT$TYPE = 2: 



TIME$OUT$TYPE = 3: 

FS$REQ$TYPE = 4: 
UC$REQ$TYPE = 5: 
FS$NAK$TYPE = 6: 
CNTRL$C$TYPE = 7: 

READSTYPE = 8: 
DFSSRD = 8: 
CLI$MSG$TYPW = 8: 



Message generated by RMX/80 when the system 
detects that an interrupt has been missed by the 
task(s) that service the interrupt level associated 
with the exchange. A message of this type is read- 
only and has a LENGTH of 5. 

Message generated by RMX/80 when a task 
times out on a timed wait. A message of this type 
is read-only and has a LENGTH of 5. 

Free Space Manager conditional allocation 
request message. 

Free Space Manager unconditional allocation 
request message. 

Free Space Manager negative acknowledge 



Message sent by the Terminal Handler to the 
RQWAKE exchange when the operator types an 
ASCII control-C on the keyboard to invoke the 
Debugger. 

Terminal Handler read request message. 
Disk File System READ request message. 
Connect Line Interpreter message. 
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RMX/80 



TYPE CODE 



DEFINITION 



CLR$RD$TYPE = 9: 

LASTSRDSTYPE = 10: 
ALARMSTYPE =11: 
WRITESTYPE = 12: 
DFS$WRT= 12: 
DFS$SK= 13: 
DFSSCLS = 14: 
DFS$OPN=15: 
DFSSRNM = 16: 
DFSSDEL = 17: 
DFSSATR = 18: 
DFSSLD = 19: 
DFSSFMT = 20: 
DFS$DSK = 21: 
AIREP = 30: 

AISQS = 31: 



AISQV = 32: 



AIRAN = 33: 



AORAN = 38: 



Terminal Handler clear-and-read request 
message. 

Terminal Handler last-read request message. 

Terminal Handler alarm output request message. 

Terminal Handler write request message. 

Disk File System WRITE request message. 

Disk File System SEEK request message. 

Disk File System CLOSE request message. 

Disk File System OPEN request message. 

Disk File System RENAME request message. 

Disk File System DELETE request message. 

Disk File System ATTRIB request message. 

Disk File System LOAD request message. 

Disk File System FORMAT request message. 

Disk File System DISKIO request message. 

Analog Input Handler request message for 
repetitive single-channel input. 

Analog Input Handler request message for 
sequential channel input with a single gain. 

Analog Input Handler request message for 
sequential channel input with variable gain. 

Analog Input Handler request message for 
random channel input. 

Analog Output Handler request message for 
random channel output. 
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APPENDIX D 
MEMORY REQUIREMENTS 



Memory Requirements for F MX/80 
Modules and Tables 

This section of the appendix lists the memory requirements for the modules included 
in Version 1.3 of RMX/80, and the additional tables required for configuration. 
Stack requirements are included in the RAM byte counts. The RAM counts for the 
Terminal Handler, Free Space Manager, and Debugger modules also include table 
allocations required for internal use. 

If your iSBC installation is equipped with a disk and you choose to use the Bootstrap 
Loader extension, many of the modules listed as having ROM requirements can be 
located entirely in RAM. In fact, all modules except the Nucleus, DISKIO and those 
contained in the Loader System Library (BOT8xx.LIB) can be moved completely out 
of ROM. As a reminder of this fact, only those modules marked with an asterisk 
must remain in ROM. 



Modules on Executive Diskette (iSBC 80/20 Version) 



Module 


ROM 


RAM 




vuy ica; 


n/\ / C\r\ XT 1 it 

80/20 Nucleus* 


900-2000 


224 


80/24 Nucleus 


900-2000 


242 


Optional Nucleus capabilities: 






RQDTSK 


73 





RQDXCH 


31 





RQSUSP 


59 





RQRESM 


46 





Terminal Handler, full (input-output version) 


3088 


941 


Terminal Handler, full (output-only version) 


935 


219 


Terminal Handler, minimal (input-output version) 


599 


156 


Terminal Handler, minimal (output-only version) 


167 


27 


Free Space Manager 


1025 


260 


Active Debugger 


11363 


1706 


Passive Debugger 


4007 


636 


Modules on Executive Diskette (iSBC 80/30 Version) 






Module 


ROM 


RAM 


(bytes) 


(bytes) 


80/30 Nucleus* 


900-2000 


242 


Optional Nucleus capabilities: 






RQDTSK 


73 





RQDXCH 


31 





RQSUSP 


59 





RQRESM 


46 





Terminal Handler, full (input-output version) 


3088 


941 


Terminal Handler, full (output-only version) 


935 


219 


Terminal Handler, minimal (input-output version) 


599 


156 


Terminal Handler, minimal (output-only version) 


167 


27 


Free Space Manager 


1025 


260 


Active Debugger 


11363 


1706 


Passive Debugger 


4007 


636 



* Those modules marked with an asterisk must remain in ROM even in systems 
incorporating the Bootstrap Loader extension. All other modules used in such a 
system can be located entirely in RAM. 
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Modules on Executive Diskette (iSBC 80/10 Version) 



Module 


ROM 

(bytes) 


RAM 

(bytes) 


5U/1U iNucieus* 


qaa onn/Y 


ZZj 


optional Nucleus capabilities: 






KyiJ 1 aK 


15 


U 




5j 


u 


R^jU or 


(SI 
/ 




RQRESM 


54 





Terminal Handler, full (input-output version) 


3268 


966 


Terminal Handler, full (output-only version) 


1194 


243 


Terminal Handler, minimal (input-output version) 


669 


156 


Terminal Handler, minimal (output-only version) 


207 


27 


Free Space Manager 


1025 


261 


Active Debugger 


11748 


1706 


Passive Debugger 


4082 


636 



Modules on Extensions Diskette 

Several points need to be noted about the byte counts listed for Disk File System 
modules. First, the numbers in parentheses in the RAM column indicate the portion 
of RAM that must be controller-addressable. Second, the total memory space re- 
quired for files is the amount specified for each open file times the maximum 
number of files that are ever open concurrently. Third, the LOAD service opens one 
file; so when LOAD is included in your system, you must take this fact into account 
in determining the maximum number of concurrently open files. 

Finally, when FORMAT is included in your system, you must also add in the byte 
counts) for one or more of the following dynamically created tasks, whichever 
one(s) are applicable to your system: FORMAT201 (standard-size single-density 
diskettes), FORMAT202 (standard-size double-density diskettes), and/or FORMAT- 
204 (mini-size diskettes). 



Module 


ROM 


RAM 


Disk File System: 
DISKIO* 


(bytes) 


(bytes) 


255 


13 


DIRSVC 


5091 


1220 (700) 


SEEK (iSBC 80/20 and 80/30 versions) 


940 





SEEK (iSBC 80/ 10 version) 


972 





LOAD 


615 


52 


FORMAT 


2172 


61 


BBFORMAT 


2936 


79 


FORMAT201 


95 





FORMAT202 


99 





FORMAT204 


95 





FORMAT206 


127 





BBFORMAT206 


148 





ATTRIB 


180 


99 


RENAME 


264 


40 


DELETE 


86 


33 


RQHD1 (iSBC 80/20 and 80/30 versions)* 


455 





RQHD1 (iSBC 80/10 version)* 


497 


20 


RQHD4 (iSBC 80/20 and 80/30 versions) 


752 





RQHD4 (iSBC 80/ 10 version) 


795 


20 


RQHD6 (iSBC 80/20 and 80/30 versions) 


576 





RQHD6 (iSBC 80/ 10 versions) 


610 


20 


Each controller task 


20 


80 (80) 


Each open file 





424 (424) 



* Those modules marked with an asterisk must remain in ROM even in systems 
incorporating the Bootstrap Loader extension. All other modules used in such a 
system can be located entirely in RAM. 
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Analog Input Handler 
Analog Output Handler 
Bootstrap Loader: 

Loader System Library 

BOT810.LIB* 

BOT824.LIB* 

BOT820.LIB* 

BOT830.LIB* 
Loaded System Library 

LOD810.LIB 

LOD820.LIB 

LOD824.LIB 

LOD830.LIB 
Command Line Interpreter 
Patch 80 Utility 

Configuration Data (All Versions) 



594 
180 



595 
557 
557 
557 






696 
2452 



21 
19 



384 (256) 
384(256) 
384(256) 
384 (256) 

216 
344 
439 
439 
170 
296 



Table 


ROM 


RAM 


(bytes) 


(bytes) 


Task Descriptor, per task 





20 


Exchange Descriptor, per exchange 





10 


Interrupt Exchange Descriptor, per interrupt exchange 





16 


Create Table 


6 





Initial Task Table, per entry 


17 





Initial Exchange Table, per entry 


2 





DFS Controller Specification Table, per entry 


7 





DSF Device Configuration Table, per entry 


5 





DFS Drive Characteristics Table (iSBC 204), number of 






entries 


1 





DFS Drive Characteristics Table (iSBC 204), per entry 


5 





DFS Buffer Allocation Block 


5 





RQNDEV (number of disk drives in system) 


1 






Stack Size Requirements for RMX/80 Operations 

The RMX/80 Nucleus operations use the stacks of the tasks that call them. 
Therefore, in order to estimate the maximum stack length required for your applica- 
tion tasks, you must know the stack requirements of the Nucleus operations. These 
are listed below. Note that these numbers do not include the two bytes required by 
the CALL instruction used to call the operation; these two bytes are part of the stack 
requirement of the user code and should be included in the stack requirement given 
by the compiler or assembler. (Refer to "Estimating Stack Length" in Chapter 3.) 

The RQENDI, RQISND, and RQCTCK operations are not included in this list, 
because these operations should not be called from user tasks. RQENDI and 
RQISND are only to be called from user-supplied interrupt service routines; 
RQCTCK (iSBC 80/10 version only) may be called only from an interrupt polling 
routine. The 24 extra bytes in the formula in Chapter 3 take into account the stack 
requirement for these operations. 



* Those modules marked with an asterisk must remain in ROM even in systems 
incorporating the Bootstrap Loader extension. All other modules used in such a 
system can be located entirely in RAM. 
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RMX/80 



Operation 



Stack 
Requirement 
(bytes) 



RQACPT 

RQCTSK 

RQCXCH 

RQDLVL 

RQDTSK 

RQDXCH 

RQELVL 

RQRESM 

RQSEND 

RQSETP 

RQSETV 

RQSUSP 

RQWAIT 



4 
8 


2 
2 

2 



2 
4 



Memory Requirements for Four 
Sample Configurations 

The following examples illustrate how you can calculate the total ROM and RAM 
requirements for your application systems. Memory requirements for the RMX/80 
Nucleus and extension tasks are obtained from the first part of this appendix; you 
must determine the memory requirements for your own tasks. (The latter must in- 
clude stack requirements; refer to Chapter 3 and to the second section of this appen- 
dix.) 



Example 1 

The following chart lists the memory requirements for a simple RMX/80 system. 
The system has four user tasks, each of which requires 700 bytes for code and 100 
bytes of data storage. The system includes the RMX/80 Nucleus and Terminal 
Handler. Notice that this system can be fully contained on an iSBC 80/20. 



Module or Table 


ROM 


RAM 


(bytes) 


(bytes) 


80/20 Nucleus 


1799 


244 


80/20 Terminal Handler (input-output version) 


3088 


941 


User Tasks 


2800 


400 


User Task Descriptors 





80 


User Exchange Descriptors (6) 





60 


User Interrupt Exchange Descriptors (2) 





30 


Initial Task Table 


68 





Initial Exchange Table 


16 





Create Table 


6 






7777 1735 
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Example 2 

The next example is for an iSBC 80/20 application system which uses the Disk File 
System. The DFS services used are OPEN, READ, WRITE, SEEK and CLOSE. 
Dynamic buffer allocation is to be used, so the Free Space Manager is included. 
There are two iSBC 201 disk controllers, each with its own task; one controller has 
two drives, the other has one. The maximum number of files open at the same time 
is two. There are two user tasks which require a total of 1250 bytes for code and 600 
bytes for data storage; 320 bytes of the data storage is controller-addressable (for 
controller task stacks and one user buffer). 

Parenthesized numbers in the RAM column indicate the portion of RAM which 
must be controller-addressable. 



Module 


KUM 

(bytes) 


RAM 

(bytes) 


80/20 Nucleus (including RQDTSK, and RQDXCH, 








which are reauired hv the Disk File Sw^terrA 


1903 


224 




Free Space Manger 


1025 


260 




DISKIO 


255 


13 




DIRSVC 


5091 


1220 


(700) 


SEEK 


940 







RQHD1 


455 







Controller tasks 


40 


160 


(160) 


Buffer space (maximum of 2 files open concurrently) 





800 


(800) 


User tasks 


1250 


600 


(320) 


User Task Descriptors 





120 




User Exchange Descriptors (4) 





40 




User Interrupt Exchange Descriptors (2) 





30 




Interrupt Exchange Descriptors 





30 




Initial Task Table 


102 







Initial Exchange Table 


12 







Create Table 


6 







Controller Specification Table 


14 







Device Configuration Table 


15 







Buffer Allocation Block 


5 







RQNDEV (number of disk drives) 


1 









11114 


3467 


(1980) 
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Example 3 

The next example shows how a minimal DFS directory-based system, using one iSBC 
201 controller and two drives, can be implemented in the iSBC 80/ 20 on-board ROM. 
361 bytes are left for a user-supplied task. 

Parenthesized numbers in the RAM column indicate the portion of RAM which 
must be controller-addressable. Asterisks indicate that the amount of RAM needed 
for buffers depends upon the application. 



(bytes) (bytes) 



80/20 Nucleus (including RQDTSK, and RQDXCH, 

which are required by the Disk File System) 
DISKIO 
RQHD1 
DIRSVC 
Controller tasks 
Buffer space 
User tasks 

User Task Descriptors 

User Exchange Descriptors (4) 

User Interrupt Exchange Descriptors 

Interrupt Exchange Descriptors 

Initial Exchange Table 

Initial Task Table 

Create Table 

Controller Specification Table 
RQNDEV (number of disk drives) 
Device Configuration Table 
Buffer Allocation Block 



1903 


224 




255 


13 




455 







5091 


1220 


(700) 


20 


80 


(80) 





* 


(*) 


361 










80 







40 







15 







15 




10 







68 







6 







7 







1 







10 







5 








8192 1672* (780)* 
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Example 4 

The next example is for a Bootstrap Loader System implemented on an iSBC 80/20 
using a Model 201 disk controller board. This is the smallest possible Loader System 
as it does not include any applications tasks. Should you wish to add applications 
tasks to the system, you also will have to consider their memory requirements. 

In the table below, those numbers enclosed in parentheses indicate the portion of 
RAM which must be controller addressable. Also, the segment of RAM allocated to 
RQPOOL can be used by other tasks when the Loader Task is inactive. 



Module 


ROM 

(bytes) 


RAM 

(bytes) 


80/20 Nucleus 


1799 


224 


Bootstrap Loader 


557 


128 


DISKIO 


255 


13 


RQHD1 


455 





Controller Task Descriptor and Stack 


20 


80 (80) 


RQPOOL 





256 (256) 


Configuration Module 


90 


200 



3176 901 (336) 



Since this system contains no tasks other than the Loader, it can load 20K bytes in 
less than 40 seconds. If additional tasks are included in the Loader System, this 
performance may be degraded. 
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APPENDIX E 
DISK FILE STRUCTURE 



This appendix describes the file structure that is used by ISIS-II and the RMX/80 
Disk File System. The information is provided for those who want to know the 
details of how files are physically represented on disk. This information is not re- 
quired to use ISIS-II or the RMX/80 Disk File System successfully. 

Information is included on file structure for standard-size single-density diskettes, 
standard-size double-density diskettes, mini-size diskettes, and hard disks. Note, 
however, that only hard disks with 128 byte sectoring and standard-size diskettes 
are ISIS-II compatible. 

General File Structure 

All ISIS-II and DFS files are made up of the same components, shown in figure E-1 . 




BLC 


CK 






SEC 


TOR 






128 BYTES 



BLC 


CK 






SECTOR 






128 BYTES 



BLC 


)CK 






SECTOR 






128 BYTES 



128 BYTES 128 BYTES 128 BYTES 128 BYTES 128 BYTES 



BLO 


CK 






SECTOR 






128 BYTES 



Figure E-1 . Disk File Components 



Each block corresponds to one disk sector, which is a hardwan 
128 bytes long. Gross disk capacities are shown below: 

Standard-Size Standard-Size Mini-Size Hard 

Single-Density Double-Density Single-Density Disk 

Tracks/ Disk 77 77 35 200 

Sectors/ Track 26 52 18 144 

Sectors/ Disk 2,002 4,004 630 28,800 

Bytes/Disk 256,256 512,512 80,640 3,686,400 

Each sector on a disk has a unique address by which it can be accessed. The address 
consists of a one-byte track number and a one-byte sector (block) number. Tracks are 
numbered 0-76 on standard-size and 0-34 on mini-size disks, and 0-199 on hard disks; 
the sectors (blocks) on a track are numbered 1-26 on standard-size single-density 
disks, 1-52 on standard-size double-density disks, 1-18 on mini-size disks, and 1-144 
on hard disks. The address of a block is also referred to as a "pointer" to that block. 
Related blocks are linked together by these pointers (that is, two of the bytes in a block 
may contain the address of another block). 
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There are two types of blocks in a file: pointer blocks and data blocks. Pointer 
blocks contain nothing but pointers to other blocks, as shown in figure E-2. 



POINTER 





BLOCK 






















LINKS 




















PREV. | NEXT 




62 DATA BLOCK POINTERS 


— H 


S 




T 


S 


T 


S 


T 


S 


T 


I* 







1 2 


3 


4 


5 


6 


7 


S 


9 


... 126 


127 



S = SECTOR« T = TRACKS 

Figure E-2. Pointer Block 


All files begin with a pointer block that is called the header block . If the file con- 
tains 62 or fewer data blocks, the header block is the only pointer block in the file. If 
there are more than 62 data blocks in the file, there is an additional pointer block for 
every 62 data blocks. A file of 300 data blocks contains 5 pointer blocks, including 
the header block. 



The first two pointers in a pointer block are links to other pointer blocks in the file. 
The first link contains the address of the previous pointer block. The header block 
always contains zeros in this field because it is the address of the first block in the 
file. The second link contains the address of the next pointer block in the file; the 
last pointer block in the file has zeros in this link. 



Following the pointer block links are 62 pointers to data blocks in the file. If a 
pointer contains zeros, then no data block has been allocated for the pointer. A zero 
pointer does not, however, necessarily mark the end of the file. Data blocks, as 
shown in figure E-3 have no particular format, since they contain user, as opposed 
to system, data. 



|< (FORMAT IS CONTEXT-DEFINED) »-| 



_l I I I I I I I L. J I I I 

1 2 3 4 5 6 7 8 ■ ■ 125 126 127 

Figure E-3. Data Block 



Data blocks are fundamentally different from pointer blocks. Data blocks are "visi- 
ble" to users; they contain the information which is transferred by read and write 
operations. Pointer blocks, on the other hand, are "invisible" to users; the data they 
contain is of interest only to the system. Where data blocks are "destinations", 
pointer blocks are "paths" to those destinations. To access user data in a file, ISIS- 
II and DFS follow a path of pointers to a data block. 



The relationship of pointer and data blocks in a file is illustrated in figure E-4. 
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PREV. NEXT (UNALLOCATED) 



TRACK 7 |~ DATA3 |o.o|3.b|4,7 | ""| DATA1 

( UNALLOCATED ) PREV. NEXT ( UNALLOCATED ) 

i | ~| DATA2 |^1.9 1.7^J | "j 



PREV. NEXT 



TRACK 9 | 

SECTOR 



(UNALLOCATED) 



jZa 0.0 2,9 aoj DATA5 DATA4 



Figure E-4. Pointer and Data Blocks in a Typical File 



The diagram is simplified in that it shows only four sectors per track (instead of 26, 52, 
18, or 144) and only two data pointers per pointer block (instead of 62). The file 
"begins" at the header block which contains pointers to the first two data blocks 
(DATA1 and DATA2). The header block is chained (linked) to a second pointer 
block located at sector 3 of track 8. This block contains pointers to DAT A3 and 
DATA4, is chained back to the header block and forward to the last pointer block 
located at sector 1 of track 9. This block contains the last data pointer in the file. 
Because it is the last pointer block, it has a backward link but no forward link. 
Notice that it is the data pointers which order the data blocks for sequential access. 
The physical location of the data blocks (and the pointer blocks, for that matter) is 
immaterial. This ability to scatter files all over the disk allows the system to make 
very efficient use of available space. Note also that the effective capacity of a disk to 
store data blocks is diminished by the number of pointer blocks on the disk. 

System Files 

All ISIS-II and DFS non-system diskettes and hard disks contain four system 
files. These are created automatically when the disk is formatted, and may be 
subsequently updated by the system. The location of these files is fixed as shown in 
table E-l. 

Table E-l . System File Map 







Standard-Size 


Standard-Size 


Mini-Size 










Diskette 


Diskette 


Diskette 


Hard Disk 


File Name 


Single-Density 


Double-Density 


Single-Density 


Single-Density 






From 


Thru 


From 


Thru 


From 


Thru 


From 


Thru 


ISIS. TO 


(Header) 


0,24' 


0.24 


0,24 


0,24 


0.16 


0,16 


0,24 


0.24 




(Data) 


0,1 


0.23 


0,1 


0,23 


0,1 


0.15 


0,1 


0,23 


ISIS. LAB 


(Header 1) 


0,25 


0,25 


0,25 


0,25 


0,17 


0,17 


0,25 


0,25 




(Data) 


0,26 


0,26 


0,26 


0,52 & 


0,18 


0,18 


0,26 


0,87 










1,26 


1,52 












(Header 2) 














0,88 


0,88 




(Data) 














0,89 


0,144 & 


















1,64 


1,69 




(Header 3) 














1,70 


1,70 




(Data) 














1,71 


1,72 & 


















1,136 


1,144 


ISIS.DIR 


(Header 1) 


1,1 


1,1 


1,1 


1,1 


1.1 


1,1 


1,1 


1.1 




(Data) 


1,2 


1,26 


1,2 


1,26 


1.2 


1,18 


1.2 


1,63 




(Header 2) 














1,73 


1,73 




(Data) 














1,74 


1,135 


ISIS.MAP 


(Header) 


2,1 


2,1 


2,1 


2,1 


2,1 


2,1 


2.1 


2,1 




(Data) 


2,2 


2,3 


2,2 


2,5 


2.2 


2,2 


2,2 


2,30 



1. Track 0. Sector 24. 
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This file contains a program called TOBOOT. When the BOOT and RESET 
buttons on the Intellec system (RESET button only on Intellec Series II) are pressed, 
this program is read in from the disk. There are two versions of TOBOOT: one for the 
ISIS-II system disks and one for all other disks. Control is passed to TOBOOT, which 
then reads in the rest of the system from the disk and displays "ISIS" and the ISIS-II 
version number on the console. If an attempt is made to boot the system from a non- 
system disk, the alternate version of TOBOOT displays "NON-SYSTEM DISKETTE 
- TRY ANOTHER" and gives control to the Monitor. 

ISIS.LAB 

The first 9 bytes of this file contain the name (label) of the disk stored in ASCII 
characters as follows: xxxxxx.yyy (name extension). The next 40 characters are 
ASCII nulls (binary zeros). The next two bytes are a carriage return and line feed 
(ODH and OAH). The next 77 bytes (35 bytes on a mini-size disk or 200 on a hard disk) 
contain a one-byte interleaving factor for each track on the disk as given in table E-2. 



Table E-2. Sector Interleaving Factors 



Disk Size and Density 


Track 


Track 1 


Remaining Tracks 


Standard-Size Single-Density 


1 


12 


6 


Standard-Size Double-Density 


1 


6 


5 


Mini-Size Single-Density 


1 


6 


6 


Hard Disk 


1 


28 


12 



The content of the remainder of the file (double-density and hard disks only) is 
undefined. 



Interleaving factors are used to speed up the sequential access of blocks on the same 
track. Often a program reads a block, does a little processing, reads the next block, 
and so on. If the blocks were stored in physically adjacent sectors, the second sector 
would be passing the head while the program was processing the first sector. The 
program would have to wait nearly one full revolution for the second sector to come 
around again. The effect of an interleaving factor of 3 is shown in figure E-5. 




Figure E-5. Sector Interleaving 
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Physical sector addresses are shown outside the "track" (which is simplified to 
depict only 18 sectors). Logical sector addresses, which are the basis for accessing 
the blocks stored in the sectors, are shown on the "track." With interleaving, a pro- 
gram which reads and processes every block in logical sequence has a processing 
"window" equivalent to the time it takes for two sectors to pass the head. Assuming 
that processing each block takes slightly less time than is available in the window, all 
18 blocks can be processed in three revolutions of the disk. Without interleaving, 18 
revolutions would be required. 



ISIS.DIR 

This file contains 25 data blocks (17 for mini-size diskettes and 124 for hard disks); 
each of these blocks has room for 8 directory entries. One entry is used for each file on 
the disk, so there is room in the directory for 200 files (136 for mini-size diskettes and 
992 for hard disks). Each directory entry is 1 6 bytes long and is formatted as shown in 
figure E-6. 
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Figure E-6. Directory Entry 
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PRESENCE is a flag which can contain one of three values: 



0OOH: The file associated with this entry is present on the disk . 



07FH: No file is associated with this entry; the content of the rest of the entry is 
undefined. The first entry with its flag set to 07FH marks the current 
logical end of the directory, and directory searches stop at this entry. 

OFFH: The file named in this entry once existed on the disk, but is currently 
deleted. The next file added to the directory will be placed in the first entry 
marked OFFH. This flag cannot, therefore, be used to (reliably) find a file 
which has been deleted. A value of OFFH should be thought of as simply 
marking an open directory entry. 

FILE NAME is a string of up to 6 non-blank ASCII characters specifying the name 
of the file associated with the directory entry. If the file name is shorter than six 
characters, the remaining bytes contain binary zero. For example, the name 
ALPHA would be stored as 414C50484100H. 

EXTENSION is a string of up to 3 non-blank ASCII characters that specify an 
extension to the file name. Extensions often identify the type of data in the file such 
as OBJ (object module), or PLM (PL/M source module). As with the file name, unused 
positions in the extension field are filled with binary zeros. 

ATTRIBUTES are bits that identify certain characteristics of the file. A 1 bit in- 
dicates that the file has the attribute, while a bit means that the file does not have 
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the attribute. The bit positions and their corresponding attributes are listed below 
(bit is the low-order or rightmost bit, bit 7 is the leftmost bit): 

0: Invisible. Files with this attribute are not listed by the ISIS-1I DIR 

command unless the I switch is used. All system files are invisible. 

1 : System. Files with this attribute are copied to the disk in drive 1 when the S 

switch is specified with the ISIS-II FORMAT command. 

2: Write-Protect. Files with this attribute cannot be opened for output or 

update, nor can they be deleted or renamed. 

3-6: These positions are reserved for future use. 

7: Format. Files with this attribute are treated as though they are 

write-protected. In addition, these files are created on a new diskette when 
the disk is formatted via the ISIS-II FORMAT command; however, the 
DFS FORMAT service does not do thjs. The system files all have the FOR- 
MAT attribute, and this attribute should not be given to any other files. 

The ISIS-II System User's Guide, 9800306, should be consulted for more informa- 
tion on attributes. 

EOF COUNT contains the number of the last byte in the last data block of the file. 
If the value of this field is 080H, for example, the last byte in the file is byte number 
128 in the last data block (the last block is full). 

NUMBER OF DATA BLOCKS is an address variable which indicates the number 
of data blocks currently used by the file. ISIS-II and the RMX/80 Disk File System 
both maintain a counter called LENGTH, which contains the current number of 
bytes in the file. This is calculated as: 

((NUMBER OF DATA BLOCKS) x 128) + EOF COUNT. 

HEADER BLOCK POINTER is the address of the file's header block. The high- 
order byte of this field is the sector number, and the low-order byte is the track 
number. The system "finds" a disk file by searching the directory for the name, 
then using the header block pointer to seek the beginning of the file. 

ISIS. MAP 

This file contains a bit map of the disk, with each bit position representing or., block 
(sector) of the disk. If a bit is 1 , the corresponding block is allocated, that is, in use as a 
pointer block or a data block. bits denote free space on the disk. When file is 
deleted, the bits that correspond to the sectors it occupied are reset to 0. On standard- 
size single-density disks, system files occupy the first two tracks and the first three 
sectors of the third track (in other words, the first 55 sectors). The >re the first 55 
bits of a standard-size single-density map are always 1 . The last 46 map bits are always 
0, since the map has 2048 bit positions and there are only 2002 sectors on a single- 
density disk. For double-density disks tne first 109 bits are always 1 and the last 92 bits 
are always 0. For mini-size disks the first 38 bits are always 1 and the last 376 are 
always 0. For hard disks the first 318 bits are always I and the last 899 are always 0. 



ISIS.BAD 

This file contains a bit map of the disk, with each bit position representing one block 
(sector) of the disk. If a bit is 1, the corresponding block is bad. bits denote blocks 
that are not bad. For hard disks, the last 899 bits are always 0. 
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Figure E-7. Disk File Structure Summary 
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File Structure Summary 



Figure E-7 provides an overall view of the most important elements in the file struc- 
ture. Some simplifications have been made for clarity (there are only four directory 
blocks, pointer blocks contain only four data block addresses, etc.), but the key rela- 
tionships of file elements are shown. 

One new concept is introduced in the drawing, Notice that IOTA's second pointer 
block contains a zero pointer between the pointer to data block 5 and the pointer to 
data block 7. Data block 6 does not exist (no space is allocated to it), but it can be 
added later, since there is a "slot" left open in the pointer block. If an attempt is 
made to read data block 6, the operation will be performed normally, but binary 
zeros will be placed in the requesting program's buffer. If an attempt is made to 
write data block 6, a new data block will be allocated and written and its address will 
be placed in the pointer block. Blocks such as data block 6, which are "logically 
allocated" but not physically allocated, are included in the NUMBER OF DATA 
BLOCKS field of the directory. 

IOTA is an example of how a "sparse" file can be implemented efficiently within 
the file structure. Such a file is created by opening the file for update and writing 
records where they occur and seeking ahead when there is no record. For example, 
assume IOTA is a file which can ultimately contain seven 128-byte records (ignore 
the EOF mark in the drawing). However, when the file is created there is no data for 
record six. The file would be created by opening it for update, writing the first five 
records in sequence, seeking ahead 128 bytes, and writing record seven. 
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APPENDIX F 
HARDWARE CONSIDERATIONS 



This appendix provides hardware installation procedures that must be performed in 
order to run your RMX/80-based software on an iSBC 80/20, 80/30, or 80/10 
system. These procedures apply in addition to the installation procedures prescribed 
in the iRMX 80 Installation Instructions, 9803087, and in the hardware manuals for 
your equipment. 

Each of the three iSBC 80 boards is discussed in a separate section. 



iSBC 80/20 

Terminal Interface 

The standard Intel terminal is cabled to communicate with an Intel Microcomputer 
Development System rather than a Single Board Computer. Therefore, an Intel 
terminal with an unmodified cable will not work with an iSBC 80/20 (or 80/30 or 
80/10). 

When using the serial I/O port, the iSBC 80 requires the Request-to-Send (RTS) 
signal at pin 8 of J3. This corresponds to pin 4 of the 25-pin serial I/O connector 
commonly in use. Adding pin 4 to the 25-pin connector CRT cable allows the CRT 
to function properly. When using a different terminal that does not generate the 
RTS signal, a jumper can be added to the iSBC 80 between pins 8 and 10 of J3, or 
between pins 4 and 5 of the 25-pin connector. This routes the iSBC-generated CTS 
(Clear-to-Send) signal back into the board as an RTS signal. 



iSBC 80/20 Interrupts 

The RMX/80 Terminal Handler uses interrupts 6 and 7 for the READ and WRITE 
interrupts, respectively. The RXRDY and TXRDY signals from the US ART (8251 
Programmable Communications Interface) are used to generate these interrupts. 
The time base used by RMX/80 is generated from the 8253 Programmable Interval 
Timer chip. 

To accomplish this interrupt configuration, the following wiring changes must be 
made: 

(1R1 - INT2 on PI) 
(OIT0 - IR2) 

Ground multiple inputs to IR7 

OIT0-IR1 
RXR - IR6 
TXR - IR7 



Bus Priority 

To use the iSBC 80/20 (or 80/30) as the bus master, you must connect its BPRN pin 
so as to grant it bus access when it needs to use the bus. This can be done by groun- 
ding the BPRN pin or by tying it to the BREQ pin to let it grant itself bus access 
when desired. 



Remove 
Connect 
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The iSBC 80 board can be plugged into any of the four slots, J2 through J5, of the 
604 card cage. It comes installed in J5 with a jumper connecting pins G - H on the 
card cage mother board. In most systems, you will probably wish to place the iSBC 
80/20 in slot J2 (top of cage) to allow the ICE-80 cable to plug in and still use the 
other slots for memory or other controllers. This requires an additional jumper to be 
installed. The table below shows the jumpers needed for each slot if the only bus 
master is the processor board. 

SLOT BPRN BREQ 

J2 B A 

J3 C D 

J4 E F 

J5 H G 



If other controllers are used, a daisy chain priority scheme must be implemented, as 
described in the iSBC 80/20 or 80/30 Hardware Reference Manual. 



ICE-80 Processor Module Jumpers 

The ICE-80 processor module must have its jumpers set for external clock and high 
frequency operation. 

External Clock A - C 

E-F 

High Frequency K - L 
J-H 



ICE-80 8259 Fix 

A small circuit board, available from Intel Customer Service, must be soldered onto 
chip A27 of the ICE-80 processor board to make it compatible with the iSBC 80/20. 
It is labeled PWA 1001359. If your system was shipped after September of 1977, 
then it already has this patch board. Otherwise, you should check visually to deter- 
mine whether it has been incorporated into your system. Its purpose is to allow for 
the iSBC 80/20's use of 3-byte calls for interrupts instead of the RST instruction. 



ICE-80 Mode Selection Switch 

A special switch must be installed on the System 80/20 to handle the acknowledge 
signals generated for I/O bus and memory acknowledges. The switch is a 3-position 
single-pole, double-throw, center-off switch whose functions are labeled LOAD, 
OFF and RUN. 

The LOAD position allows ICE-80 to load code into the iSBC 80/20 which has 
memory mapped physically into the Intellec development system. The ICE-80 
module writes out the memory address and data to both the iSBC and development 
systems and must get an acknowledge from both systems. Otherwise, ICE-80 reports 
an error 67 (250 msec time out), which aborts the load process. When loading code 
into mapped memory, it is common to have no equivalent memory in the iSBC or 
for that memory to be ROM. In either case, this gives no acknowledge. A pseudo- 
acknowledge can be created by grounding pin 137, which gives an immediate 
acknowledge of the iSBC memory access. 

The OFF position of the switch is useful for normal operation of the iSBC 80/20 
without ICE-80 and with its own full complement of ROM and RAM. 

The RUN position of the switch allows ICE-80 to get off-board acknowledges for all 
memory accesses to nonexistent memory; however, it will not acknowledge a write 
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to the on-board ROM, thus causing errors. These errors can be prevented with the 
following modifications: 



Disconnect 1 ms time out 1 37- 1 38 

Connect switch terminal 1 to pin 135 
Connect switch terminal 2 to pin 137 
Connect switch common to pin 53 (ground) 

An alternate, and often better, solution is to avoid memory mapping by having all 
RAM memory in your iSBC system. 

Accessing Memory in an iSBC 80 System Using ICE-80 

There are two ways a user may wish to allocate memory in a system using both 
ICE-80 and a System 80/20 (or 80/10). The first is to use only Intellec Development 
System memory and map it into the iSBC 80 logical memory space. The use of the 
LOAD/RUN switch for this technique was described previously. This technique has 
the limitation of providing insufficient memory for large programs with correspon- 
dingly large symbol tables, since 12K is used for ISIS-II, 12 K for ICE-80, and 2K 
for the Monitor. This leaves 38K of Intellec Development System memory to be split 
between the symbol table and the mapped code. 



To obtain more usable memory, 16K or 32K RAM boards may be plugged into the 
System 80/20 card cage. Up to four boards may be added when a 614 expansion 
chassis is used. The on-board PROM and RAM always take precedence over the off- 
board memory in the system. To bypass the on-board PROM, block (0-4K) of 
memory must be mapped from the Development System using the command: 



XFORM MEMORY INTO 6 



The 2K* of on-board RAM are used instead of the equivalent addresses of the 16K 
RAM board. A memory map would look like: 



0- 4K DEVELOPMENT SYSTEM MAPPED MEMORY 

4-14K" 1st16K RAM BOARD 

14-16K*** ON BOARD MAP 

16-32K 2nd 16K RAM BOARD 

32-48K 3rd 16K RAM BOARD 

48-64K 4th 16K RAM BOARD 



* 4K for the iSBC 80/2(M; IK for the iSBC 80/10. 
** 4-12K for the iSBC 80/20-4; 4-15K for the iSBC 80/10. 
*»* 12-16K for the iSBC 80/20-4; 15-16K for the iSBC 80/10. 







To use memory in this way requires the LOAD/RUN switch to function differently: 
the LOAD setting must generate an acknowledge for stores into PROM. The 
acknowledge cannot be immediate as with Development System memory. An im- 
mediate acknowledge when storing into iSBC RAM is premature. Instead, wait for 
the normally generated RAM board acknowledge. The 10-ms timer on the iSBC 
80/20 can be used to generate the PROM write acknowledge by connecting pins 1 37 
and 138 via the switch's LOAD setting. 

The RUN position needs no connections, since all acknowledges are properly 
generated by the standard hardware. The 10-ms timeout should not be connected, so 
that inadvertent stores to PROM may be caught by ICE-80 error 67 (timeout). Note 
that the two modes of using memory are mutually exclusive. Additional Develop- 
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memory that do not already have physical memory in place. 1 he only reason the 
first 4K may use Development System mapped memory is that the iSBC 80 generates 
acknowledges for reads to these addresses. If no RAM board is in place for iSBC 
memory space 48K to 64K, Development System memory mapped here will not get 
access acknowledged, and ICE-80 will generate error 67 timeouts. 

iSBC 80/24 

Terminal Interface: 

The iSBC 80/24 board serial port is configured to the RS 232C data set mode. In this 
configuration the board will not transmit data until a Request To Send (RTS) signal 
is received by the board on J3 - 8. If your terminal does not supply RTS, the follow- 
ing modifications are required: 

a. Remove factory installed header in J4. 

b. Add a wire jumper between pins 3 and 4. 

c. Install the header back into J4. 

This modification enables the board to supply its own RTS signal. 

If your terminal requires a current loop (TTY) interface, refer to the iSBC 80/24 
board hardware reference manual for instructions for installing the iSBC 530 TTY 
Adapter Module. 

iSBC 80/24 Interrupts: 

The RMX/80 Terminal Handler uses board interrupts 6 and 7 for the READ and 
WRITE commands. These interrupts are driven by RXRDY and TXRDY from the 
on-board Programmable Communications Interface (8251 A US ART). The handler 
also requires Interval Timer output to be connected to interrupt level 1 . To enable 
these interrupts you must alter the board's factory jumper configuration, as follows: 

a. Remove these board jumper connections: 

83 - 84 
101 - 106 

100 - 118 

b. For TXRDY (interrupt level 7) install jumper connection 

83-115 

c. For RXRDY (interrupt level 6) install jumper connection 

96 - 117 

d. For Interval Timer output install jumper connection 

101 - 118 

e. The following interrupt matrix jumpers should be verified and installed if the 
board is not in the default configuration: 

86 - 87 

85 - 86 

84 - 85 

119 - 120 

120 - 121 

121 - 122 

122 - 123 
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Multibus™ Priority: 

Refer to the iSBC 80/24 board hardware reference manual (order number 142648). 
iSBX Bus Connectors and Multimodule Boards: 

The iSBC 80/24 board is equipped with two iSBX Multimodule connectors. These 
connectors use I/O ports CO - CF and F0 - FF when Multimodule boards are 
installed. However, these ports may be used for other applications if Multimodule 
boards are not installed. Refer to the iSBC 80/24 board hardware reference manual 
for more information on the iSBX Bus connectors. 



USING ICE 85 

Jumpering that supports the use of 1CE-85 depends upon the intended distribution of 
memory. 

When all memory is mapped into the Intellec system and does not exist on the iSBC 
80/24 board, ground pin 143 by jumpering 26-143. This will allow the appropriate 
acknowledge signals to be generated even though no physical memory exists. (In this 
case, it does not matter whether the 10 millisecond time-out circuitry is in place.) 

If some, but not all, memory is to be mapped to the Intellec system, pin 143 must not 
be grounded. Grounding of this pin would prevent the proper operation of memory 
on the iSBC 80/24 board, because acknowledge signals would be generated 
immediately on all read and write requests. Instead, use the iSBC 80/24 time-out 
feature, which delays access to Intellec memory by 10 milliseconds. Time out is 
implemented by jumpering 140-143. 

To access memory locations that are normally dedicated to PROM, the PROM 
memory must be disabled. To do this, ground pin 54 by jumpering 54-55. 

iSBC 80/30 

Terminal Interface 

Refer to "Terminal Interface" in the iSBC 80/20 section of this appendix. 



iSBC 80/30 Interrupts 

The RMX/80 Terminal Handler uses interrupts 6 and 7 for the READ and WRITE 
interrupts, respectively. The RXRDY and TXRDY signals from the USART (8251 
Programmable Communications Interface) are used to generate these interrupts. 
The time base used by RMX/80 is generated from the 8253 Programmable Interval 
Timer chip. 



To accomplish this interrupt configuration, the following wiring changes must be 
made: 



Remove 



Connect 



123- 


138 


46- 


47 


47- 


52 


141 - 


132 


47- 


51 


143- 


127 


142 - 


126 


145- 


140 



(COUNT OUT - INTR 7.5) 
(CLK1 - CLK0) 
(CLK0 - CLK2) 
(EVENT CLK - IR1) 
(CLK0 - A12-11) 
(RXR INTR - IR6) 
(TXR INTR - IR7) 
(Ground - INTR 5.5) 
(Ground 
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Bus Priority 

Refer to "Bus Priority" in the iSBC 80/20 section of this appendix. 

Accessing Memory in an iSBC 80/30 System Using ICE-85 

ICE-85 provides two modes of memory access, USER and INTELLEC. When 
referencing memory mapped to the USER system, ICE-85 expects an acknowledge 
signal from the user memory. When referencing memory mapped into the IN- 
TELLEC, ICE-85 expects two such acknowledge signals, one from the user system 
and one from the Intellec. 

If all memory accessed by a user program is of type USER, physical memory must 
be present in the selected address locations. In this case the actual memory device 
will generate the needed acknowledge signal for read and write operations, (except 
for on-board PROM; see below). 

If all memory accessed by a user program is of type INTELLEC, no physical 
memory need be present in the user system. The necessary acknowledge signals from 
the user system will be properly generated if pin 1 16 is connected to ground. 

If some of the memory is USER and some is INTELLEC, a number of problems 
arise. First, the grounding of pin 116 to handle INTELLEC mapped memory (see 
preceding paragraph) will prevent proper operation of any physical memory in the 
user system, since the acknowledges will be immediately generated upon all read or 
write requests. These extra acknowledges will cause the system to act as if the data 
were already present, when in fact it is not. 

The only solution is to use the iSBC 80/30 10-microsecond timeout feature. This 
feature delays acknowledges of access to INTELLEC memory by 10ms. Clearly, this 
significantly decreases system throughput, since memory access normally requires 
less than 1 us. To activate the timeout feature, connect pins 115-116 (disconnect pin 
116 from ground before making this connection). 

A final problem concerns the use of on-board PROM. If you wish to access the 
memory locations normally found in PROM, without actually using PROMs, how 
do you properly load the code? The solution depends on the type of memory map- 
ping used. If memory is mapped to the USER system, the PROMs can be disabled 
by connecting pins 27 - 4, forcing the iSBC 80/30 to go off-board to find this portion 
of memory. Then, by placing bus memory at location zero, you force the 80/30 to 
use off-board RAM instead of PROM. When memory is mapped to the Intellec, 
either the timeout feature of the immediate acknowledge solutions described above 
may be used. 



iSBC 80/10 

Terminal Interface 

Refer to "Terminal Interface" in the iSBC 80/20 section of this appendix. 



iSBC 80/10 Interrupts 

The RMX/80 Terminal Handler uses interrupts 6 and 7 for the READ and WRITE 
interrupts, respectively. The RXRDY and TXRDY signals from the USART (8251 
Programmable Communications Interface) are used to generate these interrupts. 
The time base must be supplied via external hardware such as the iSBC 104 combina- 
tion expansion board; refer to Appendix G for further information and guidelines. 
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iSBC 80/10 Baud Rate Selection 

The effective baud rate for terminal input is determined by the wire-wrap jumper 
connection selected in accordance with baud rate selection information in the iSBC 
80/ 10 and iSBC 80/ 10A Hardware Reference Manual, 9800230 or the iSBC 80/ 10B 
Hardware Reference Manual, 9803119. 

If the user program specifies a baud rate of 9600 (by setting RQRATE to 7), 
RMX/80 sets the baud rate factor (see Hardware Reference Manual) to 16. For any 
other value of RQRATE, RMX/80 sets the baud rate factor to 64, and the jumper 
connection selected in accordance with the Hardware Reference Manual should cor- 
respond to the appropriate baud rate for the factor. 



ICE-80 Mode Selection Switch 

A special switch must be installed on the System 80/10 to handle properly the 
acknowledge signals generated for I/O, bus and memory acknowledges. The switch 
is a 3-position single-pole, double-throw, center-off switch whose functions are 
labeled LOAD, OFF and RUN. 

The LOAD position allows ICE-80 to load code into the iSBC 80/10 which has 
memory mapped physically into the Intellec development system. The ICE-80 
module outputs the memory address and data to both the iSBC and MDS systems 
and must get an acknowledge from both systems. Otherwise, ICE-80 reports an er- 
ror 67 (250 msec time out), which aborts the load process. When loading code into 
mapped memory, it is common to have no equivalent memory in the iSBC or for 
that memory to be ROM. In either case, this gives no acknowledge. A pseudo- 
acknowledge can be created by grounding pin 52, which gives an immediate 
acknowledge of the iSBC memory access. 

The OFF position of the switch is useful for normal operation of the iSBC 80/10 
without ICE-80 and with its own full complement of ROM and RAM. 

The RUN position of the switch is arrived at by removing the ground from pin 52 
(turning the switch to the center-off or position opposite LOAD). 

If the system is in an intermediate stage of development in which part of the memory 
used is on-board or off-board RAM and part is mapped into the Intellec develop- 
ment system via ICE-80 (i.e., neither all mapped nor all physical memory), addi- 
tional hardware modifications are necessary. These are described in the following 
section. 

Note that the Disk File System services will not operate on a system in which all 
memory is mapped via ICE-80. Sufficient off-board RAM must be available on the 
bus for the direct memory access (DMA) operations performed by DFS. 



Additional Hardware Modifications for ICE-80 

If the memory in your system is a combination of physical memory (on- and/or off- 
board RAM) and mapped memory, the immediate acknowledge generated by groun- 
ding pin 52 (via LOAD position of mode selection switch) cannot be used. In this 
case the switch should be set to RUN and additional hardware added to the system 
to generate the required acknowledge signals. Physical memory must be present to 
occupy all of the address space mapped into the Intellec system via ICE-80. 

As an example, assume that the physical memory in your system consists of 4K of 
PROM (addresses 0-4K) and IK of RAM (addresses 15-16K) on an iSBC 80/10 
board, and 16K of controller-addressable RAM on an iSBC 016 memory expansion 
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board (addresses 48-64 K); and assume that you are mapping the address space from 
0-8K and 15-16K into an Intellec system via ICE-80. No physical memory occupies 
the address space from 4-8K. Here are two ways you could provide hardware to sup- 
ply the required acknowledge signals: 

a. Include another iSBC 016 board in your system, jumpering it to occupy ad- 
dresses 0-16K. However, note that this memory must not be used for data. 
This is because overlapping acknowledge signals from the 80/10 board and the 
auxiliary memory board, occurring when memory locations in the range 0-4K 
or 15-16K are addressed, may cause the data to be unreliable. 

b. Jumper memory from an iSBC 104 or 108 expansion board to occupy ad- 
dresses 4-8K. This memory may be used for data, since there is no overlap in 
hardware addresses. 

Accessing Memory in an iSBC 80/10 Using ICE-80 

Refer to "Accessing Memory in an iSBC 80 System Using ICE-80" in the iSBC 
80/20 section of this appendix. 

iSBC 80/10B 



Terminal Interface: 

The iSBC 80/ 10B board serial port is configured as a data terminal for interfacing to 
a TTY current loop 1/ O device. If you need to convert the board to an RS 232C inter- 
face, refer to the iSBC 80/ 10B board hardware reference manual, order number 
9803119. 



iSBC 80/1 OB Interrupts 

The RMX/80 Terminal Handler uses board interrupts 6 and 7 for the READ and 
WRITE commands. These interrupts are driven by RXRDY and TXRDY from the 
on-board Programmable Communications Interface (8251 A USART). To enable 
these interrupts you must alter the board's factory jumper configuration, as follows: 

For RXRDY, remove jumper connection 74 - 75 and install 73 - 74. 
For TXRDY, remove jumper connection 76 - 78 and install 78 - 79. 



iSBC 80/10B Time Base 

The iSBC 80/10B board is equipped with timer circuitry which can be jumpered to 
produce the required time base for RMX/80. To enable this circuitry, the following 
modifications are required: 

a. Remove jumper connection 5 - 10. 

b. Install the following jumpers: 

8 - 10 
7-11 
15 - 17 

These modifications, in conjunction with the RMX/80 timer driver written for the 
iSBC 80/ 10B parallel port E6, will supply the required time base. If you are 
reconfiguring parallel ports E4 and E5, ensure that this will not effect port E6 mode. 
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Refer to the iSBC 80/ 10B board hardware reference manual for more information on 
port restrictions. 

iSBC 80/10B Baud Rate Selection 

The iSBC 80/10B board is configured at the factory for 110 baud, which is 
compatible with most teletypewriter 1/ O devices. If you need to convert to a different 
baud rate, refer to the iSBC 80/ 10B board hardware reference manual, order number 
9803119. 

If the user program specifies a baud rate of 9600 (by setting RQRATE to 7), 
RMX/80 sets the baud rate factor (see the iSBC 80/10B Hardware Reference 
Manual) to 16. For any other value of RQRATE, RMX/80 sets the baud rate factory 
to 64, and the jumper connection selected in accordance with the Hardware 
Reference Manual should correspond to the appropriate baud rate factor. 

Multibus™ Priority 

The iSBC 80/ 10B board is classified as a limited master board, and therefore cannot 
have highest system priority when using certain other boards, such as the iSBC 204 
Disk Controller board. Refer to the iSBC 80/ 10B board hardware reference manual 
for more Multibus priority information. 

iSBX Bus Connector and Multimodule Boards: 

The iSBC 80/ 10B board is equipped with one iSBX Multimodule connector. This 
connector uses I/O ports F0 - FF when a Multimodule board is installed. However, 
these ports may be used for other applications if a Multimodule board is not 
installed. Refer to the iSBC 80/ 10B board hardware reference manual for more 
information on the iSBX Bus connectors. 

Using ICE 80 

Jumpering that supports the use of ICE-80 depends upon the intended distribution of 
memory. 

When all memory is mapped into the Intellec system and does not exist on the iSBC 
80/10B board, ground pin 90 by jumpering 25-90. This will allow the appropriate 
acknowledge signals to be generated even though no physical memory exists. (In this 
case, it does not matter whether the 10 millisecond time-out circuitry is in place.) 

If some, but not all, memory is to be mapped to the Intellec system, pin 90 must not 
be grounded. Grounding of this pin would prevent the proper operation of memory 
on the iSBC 80/24 board, because acknowledge signals would be generated 
immediately on all read and write requests. Instead, use the iSBC 80/ 10B time-out 
feature, which delays access to Intellec memory by 10 milliseconds. Time out is 
implemented by jumpering 106-107. 

To access memory locations that are normally dedicated to PROM, the PROM 
memory must be disabled. To do this, remove all of the jumpers on both J6 and J7. 
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In an iSBC 80/10 system an external clock interrupt (e.g., the 1-ms clock on the 
iSBC 104, 108, 116, or 517) must be supplied to provide timing functions to the 
system. RMX/80 (see Appendix I) provides default time base service routines 
specific to the use of any of the abovementioned boards as an external clock source; 
however, another clock source may be used instead. 

If an iSBC 104 combination expansion board is being used to generate a time base, 
the I/O address for the interrupt mask register on the iSBC 104 board must be set to 
base address DO. This is done by jumpering 1-4 on block S2. 

A supplemental interrupt polling routine (RQTPOL) is provided in the Demonstra- 
tion System (see Appendix I) for the clock signal, and level 1 is reserved for its use. 
Given that the iSBC 104 is set up to generate interrupts at the rate of 1 per millise- 
cond, the RMX/80 clock logic for the iSBC 80/10 counts 50 ticks before updating 
the Delay List, thus maintaining the 50-ms time quantum as supplied in the iSBC 
80/20 and 80/30. Note, however, that this default count value of 50 can be over- 
ridden. This is because the iSBC 80/10 version of RMX/80 uses a user-defined 
public address variable, RQTCNT, which defines the number of clock 'ticks' in a 
system time unit. For example, if a clock that generates interrupts every 25 
milliseconds is being used, the following statement will provide the clock tick value: 

DECLARE RQTCNT ADDRESS PUBLIC DATA (2); 

If RQTCNT is not supplied, it will be defaulted to 50 from the UNRSLV.LIB file. 
Note that other interrupts may share level 1 only if code is added to RQTPOL to 
handle them. 

Choosing a Clock Source 

Several things should be considered in choosing a clock source for your iSBC 80/10 
system. 

First of all, it is required that an interrupt from the clock be able to be sensed by the 
software. This is necessary so that the interrupt polling routines can determine 
whether the clock generated an interrupt. 

Second, it should be noted that the frequency of the external clock has a direct im- 
pact on the amount of processor time available to the application code. It is strongly 
recommended, therefore, that a clock interrupt period of less than one millisecond 
be avoided, and a lower-frequency time base is desirable. Overhead is minimized 
when the number of clock interrupts per system time unit is minimized. As an exam- 
ple, the fact that the iSBC 104 has no programmable counters makes it necessary for 
the processor to service directly every clock pulse as an interrupt. At the rate of one 
clock pulse every millisecond, approximately 10% to 15% of the processor time will 
be used up in interrupt processing. 

High clock frequency may actually cause clock interrupts to be missed. This can oc- 
cur when processing of one clock interrupt requires the transfer of a task from the 
Delay List to the Ready List, since during part of this transfer all interrupts are 
disabled. If a second clock interrupt occurs at such a time and the clock interrupt is 
not latched (see next paragraph), the second interrupt will be missed. If the clock in- 
terrupt is latched and a second and third clock interrupt occur during such a 
transfer, the third clock interrupt will be missed. A clock interrupt will also be 
missed if it occurs during the execution of a task with software priority higher than 
or equal to 128, since the iSBC 80/10 version of RMX/80 disables all interrupts 
while such a task is running. 
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i xuru, it, is recommenaea mat tne ciock interrupt De latched and that it be resettabie 
by the software. Latching capability will minimize the chance of missing an 
interrupt (see paragraph above). A software-resettable latch will allow you to avoid 
the possibility of the same timer interrupt being serviced (and therefore counted) 
twice. 

Fourth, since RMX/80 requires clock interrupts to be present only when one or 
more tasks have requested delays, efficiency can be increased if the timer interrupt 
can be masked off or otherwise disabled when not in use. 

Timing Variables for Disk File System 

The Disk File System references two EXTERNAL variables pertaining to timing 
features. For the iSBC 80/20 and 80/30, whose clock periods are fixed, the 
DFSUNR.LIB default values for these variables should be used, and the user need 
not be concerned with them. However, for the iSBC 80/10 (unless a 50-ms System 
Time Unit is used), these variables must be declared PUBLIC and assigned values 
corresponding to the period of the clock being used. 

RQTOV specifies the number of System Time Units DFS is to wait before returning 
an error code 43 (drive timeout) if a drive being accessed does not respond. The 
DFSUNR.LIB default is 200 System Time Units, or 10 seconds. For iSBC 80/10 
systems, it is recommended that a value be assigned to RQTOV such that the 
timeout period is approximately 10 seconds. For instance, if you are using a System 
Time Unit of 20 ms, the recommended value for RQTOV is 500. 



RQMOTM is used to determine the time delay supplied by the MOTOR ON opera- 
tion of the DISKIO service, which is required when using mini-size diskette drives. 
Like RQTOV, this value specifies a number of System Time Units. The 
DFSUNR.LIB default is 20 System Time Units, or 1 second. For an 80/10 system, 
you should assign the value that is equivalent to 1 second in your system. For 
example, if your System Time Unit is 20 ms, you should initialize RQMOTM to 50. 

Time Base Service Operations 

For an iSBC 80/10 system, you must provide routines for certain time base service 
operations referenced by RMX/80. Specifications for these operations are given 
later in this section. Note that although the specifications are given in the same for- 
mat as the specifications of RMX/80 Nucleus operations in Chapter 2, these opera- 
tions are not part of the Nucleus and must be supplied by the user. The UNR- 
SLV.LIB default for RQCLKI and RQINTI is a null procedure that simply returns. 
No default routines are provided for RQSTPC, RQSTRC, or the timer polling 
routine (called RQTPOL in the Demonstration System). 

The iSBC 80/10 version of the RMX/80 Demonstration System provides versions of 
RQINTI, RQSTPC, RQSTRC, and RQTPOL for use with the iSBC 104, 108, 116, 
or 517 as an external clock source. (RQCLKI is not required when one of these 
boards is used.) 

Specifications 

RQCLKI (Clock Initialize) Operation. 

Function. This procedure should perform any operations necessary to initialize the 
hardware that is being used to generate the clock interrupt. RQCLKI is called from 
within a critical region (a "protected" section of code which executes with all inter- 
rupts disabled) in the RMX/80 START module. 



RQCLKI: PROCEDURE PUBLIC; 



END RQCLKI; 



Description. RQCLKI takes no parameters and need not be reentrant. 

This procedure must not enable interrupts or send messages to any exchanges that it 
does not itself create, since the exchanges specified in the Initial Exchange Table 
have not been created when this procedure is called. The clock hardware should be 
initialized so that it does not generate interrupts until RQSTRC is called. If this is 
not possible, a software flag mechanism should be used. (See the description of the 
RQSTRC operation for further information.) 

If the user is providing the clock interrupt with a programmable counter, this 
routine would do the necessary programming to initialize the counter. 

RQINTI (Interrupt Initialize) Operation. 



Function. This procedure should perform any operations necessary to initialize the 
interrupt hardware environment of the iSBC 80/10. RQINTI is called from within a 
critical region in the RMX/80 START module. 



Format. 

RQINTI: PROCEDURE PUBLIC; 
END RQINTI; 

Description. RQINTI takes no parameters and need not be reentrant. 

This procedure must not enable interrupts or send messages to any exchanges that it 
does not itself create, since the exchanges specified in the Initial Exchange Table are 
not created when this procedure is called. It is intended that this procedure be used 
only for initialization of external hardware and/or setting of polling routine ad- 
dresses via the RQSETP facility. 

The Demonstration System version of this procedure, designed for use with the 
clock on the iSBC 104, 108, 116, or 517 expansion board, resets the onboard 
US ART (8251 Programmable Communications Interface chip), calls RQSETP to 
set up RQTPOL (see below) as the pseudo-level 1 interrupt procedure, and sets the 
expansion board mask to mask off all its interrupts. (In the process it resets the ex- 
pansion board clock flip-flop.) 

RQSTPC (Stop Clock) Operation. 

Function. This procedure should perform the operations necessary to stop the clock 
interrupt. It is called by the RMX/80 Nucleus when the time base is no longer re- 
quired — i.e., when no more tasks are requesting timed waits. 
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Format. 

RQSTPC: PROCEDURE PUBLIC; 



END RQSTPC; 



Description. RQSTPC takes no parameters and need not be reentrant. 

This procedure should mask off the clock interrupt, if possible. If this cannot be 
done, a software flag mechanism can be used. See the description of RQSTRC for 
more information. 

The Demonstration System version of this procedure performs the operations 
necessary to mask off the clock interrupt when the iSBC 104, 108, 1 16, or 517 is be- 
ing used to generate this interrupt (and nothing else). 

RQSTRC (Start Clock) Operation. 

Function. This procedure should perform any operations necessary to enable the 
clock interrupt. It is called by the RMX/80 Nucleus when the time base is required 
— i.e., when a task makes a timed wait request. 

Format. 

RQSTRC: PROCEDURE PUBLIC; 
END RQSTRC; 



Description. RQSTRC takes no parameters and need not be reentrant. 

If the clock interrupt cannot be masked off or otherwise stopped, a software flag 
mechanism can be used. In this case the RQCLKI routine should initialize a flag to a 
"stopped" state, RQSTRC should set the flag to the "started" state, and RQSTPC 
(see above) should set it to the "stopped" state. This flag should be tested by the 
level-one polling routine. It should call the procedure RQCTCK if and only if this 
flag is in the "started" state. It is very important that RQCTCK not be called when 
the flag is in the "stopped" state. The flag mechanism described above will not be 
necessary if the clock interrupt is disabled by RQSTPC is such a way that no clock 
interrupts are generated, and if the level-one interrupt routine accrately can deter- 
mine whether a particular interrupt was caused by the clock hardware. 

The Demonstration System version of this procedure performs the operations 
necessary to enable the clock interrupt when the iSBC 104, 108, 116, or 517 is being 
used to generate this interrupt (and nothing else). 

RQTPOL (Timer Poll) Operation. 

Function. This procedure serves as one of the user-supplied interrupt polling 
routines (see "iSBC 80/10 Interrupts" in Chapter 2). It is used by the Demonstra- 
tion System to recognize the Clock interrupt from the iSBC 104, 108, 116, or 517 
board. 
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Format. 



RQTPOL: PROCEDURE BYTE PUBLIC; 



RETURN OFFH; 



/* TRUE */ 



RETURN 00H; 



/* FALSE */ 



END RQTPOL; 



Description. RQTPOL takes no parameters and need not be reentrant. The pro- 
cedure must return a boolean value (TRUE = OFFH or FALSE = 00H). 



This procedure is provided by the Demonstration System as the level-one polling 
routine and serves as the timer poll. The Demonstration System version of RQINTI 
calls RQSETP to establish this correspondence. Whenever RQTPOL determines 
that the iSBC 104, 108, 116, or 517 clock hardware has generated an interrupt, it 
calls RQCTCK. 

If you wish to have more than one interrupt source share pseudo-level 1 , you should 
provide your own polling routine via RQSETP (see Chapter 2). This routine should 
call RQCTCK whenever a clock interrupt is generated; it should also reset the clock 
interrupt. Your timer polling routine may have a name of your own choosing; since 
the name is not referenced by RMX/80, it need not be RQTPOL. 



The following two examples are written for use with the clock on the iSBC 104, 108, 
116, or 517 expansion board. Example 1 consists of the timer routines in the 
Demonstration System, which make use of the hardware interrupt enable/disable 
feature of the expansion boards. Example 2 uses software to logically enable and 
disable the clock interrupt. This type of logical enable/disable must be performed if 
your external clock source does not have a hardware enable mask. 



Example 1 

/* MODULE: SBC104 

LAST CHANGED: 21 NOVEMBER 1977 

THIS MODULE CONTAINS THE ISBC 104 SPECIFIC PROCEDURES FOR HANDLING 

THE TIMER INTERRUPTS, SETTING THE INTERRUPT MASK, ETC. 

*/ 

SBC104:DO; 
SNOLIST 

SINCLUDE (:F2:COMMON.ELT) 
SINCLUDE (:F2:EXCH.ELT) 
SINCLUDE (:F2:8010.ELT) 
SINCLUDE (:F2:IED.ELT) 
SINCLUDE (:F2:SYNCH.EXT) 
SINCLUDE (:F2:INTRPT.EXT) 
SLIST 



Sample Timing Routines 
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RQCTCK: PROCEDURE EXTERNAL; 
END RQCTCK; 

/* PUBLIC PROCEDURE: RQTPOL 
THIS PROCEDURE IS THE TIMER POLLING ROUTINE FOR THE ISBC 104 BOARD. 

*/ 

RQTPOL: PROCEDURE BYTE PUBLIC; 

IF (INPUT(ODOH) AND 01 H) THEN 

DO; 

/* THIS IS YOUR TIMER INTERRUPT 

*/ 

OUTPUT(0D2H) = 0; 
CALL RQCTCK; 
RETURN TRUE; 
END; 

RETURN FALSE; 
END RQTPOL; 

/* PUBLIC PROCEDURE: RQINTI 

THIS PROCEDURE IS THE INTERRUPT INITIALIZATION ROUTINE FOR THE ISBC 104. 



RQINTI: PROCEDURE PUBLIC; 

1* RESET THE USART TO PREVENT STRAY LEVELS FROM CAUSING UNWANTED 
INTERRUPTS 

*/ 

OUTPUT(USART$CONTROL); 

OUTPUT(USARTSCONTROL); 

OUTPUT(USART$CONTROL); 

OUTPUT(USARTSCONTROL) = 0; 

OUTPUT(USART$CONTROL) = USARTSRESET; 

OUTPUT(USART$CONTROL) = STOPS1 OR CL8 OR RATES64X; 

OUTPUT(USART$CONTROL) = RTS OR ERRORSRESET OR DTR; 

OUTPUT(USARTSOUT) = 0FFH; 

IF INPUT(USARTSIN) THEN; 

CALL RQSETP(.RQTPOL,1); 

OUTPUT(0D3H) = OH; /* SET INTERRUPT MASK */ 
END RQINTI; 

/* PUBLIC PROCEDURE: RQSTRC 

THIS PROCEDURE IS THE USER DEFINED PROCEDURE FOR TURNING ON THE 

REAL TIME CLOCK ON THE ISBC 104 BOARD. THE CLOCK IS TURNED ON BY ENABLING 

THE INTERRUPT MASK BIT ASSOCIATED WITH THE TIMER INTERRUPT. THE 

TIMER IS ALSO RESET WHEN THE NEW INTERRUPT MASK IS LOADED. 

*/ 

RQSTRC: PROCEDURE PUBLIC; 
OUTPUT(0D3H) = 01 H; 
END RQSTRC; 

/* PUBLIC PROCEDURE: RQSTPC 

THIS PROCEDURE IS THE USER-CODED ROUTINE THAT DISABLES THE TIMER INTERRUPT. 
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*/ 

RQSTPC: PROCEDURE PUBLIC; 
OUTPUT(0D3H) = 0; 
END RQSTPC; 
END; 

Example 2 



/* MODULE: SBC104 
LAST CHANGED: 21 NOVEMBER 1977 

THIS MODULE CONTAINS THE ISBC 104 SPECIFIC PROCEDURES FOR HANDLING 
THE TIMER INTERRUPTS, SETTING THE INTERRUPT MASK, ETC. 

*/ 

SBC104:DO; 
$NOLIST 

$INCLUDE (:F2:COMMON.ELT) 
SINCLUDE (:F2:EXCH.ELT) 
SINCLUDE (:F2:8010.ELT) 
SINCLUDE (:F2:IED.ELT) 
$INCLUDE (:F2:SYNCH.EXT) 
SINCLUDE (:F2:INTRPT.EXT) 
SLIST 

RQCTCK: PROCEDURE EXTERNAL; 
END RQCTCK; 

DECLARE TIMERSENABLED BYTE; 

/* PUBLIC PROCEDURE: RQTPOL 
THIS PROCEDURE IS THE TIMER POLLING ROUTINE FOR THE ISBC 104 BOARD. 

*/ 

RQTPOL: PROCEDURE BYTE PUBLIC; 

IF (INPUT(ODOH) AND 01 H) THEN 

DO; 

/* THIS IS YOUR TIMER INTERRUPT 

OUTPUT(0D2H) - 0; 
IF TIMERSENABLED THEN 
CALL RQCTCK; 
RETURN TRUE; 
END; 

RETURN FALSE; 
END RQTPOL; 

/* PUBLIC PROCEDURE: RQINTI 

THIS PROCEDURE IS THE INTERRUPT INITIALIZATION ROUTINE FOR THE ISBC 104. 

*/ 

RQINTI: PROCEDURE PUBLIC; 
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INTERRUPTS 

*/ 

OUTPUT(USART$CONTROL); 

OUTPUT(USART$CONTROL); 

OUTPUT(USART$CONTROL); 

OUTPUT(USART$CONTROL) = 0; 

OUTPUT(USARTSCONTROL) = USARTSRESET; 

OUTPUT(USART$CONTROL) = STOP$1 OR CL8 OR RATES64X; 

OUTPUT(USART$CONTROL) - RTS OR ERRORSRESET OR DTR; 

OUTPUT(USART$OUT) = OFFH; 

IF INPUT(USARTSIN) THEN; 



CALL RQSETP(.RQTPOL,1); 

OUTPUT(0D3H) = 01H; /* ENABLE THE CLOCK INTERRUPTS */ 
TIMERJENABLED = FALSE; 

END RQINTI; 



/' PUBLIC PROCEDURE: RQSTRC 

THIS PROCEDURE IS THE USER-DEFINED PROCEDURE FOR TURNING ON THE REAL- 
TIME CLOCK ON THE ISBC 104 BOARD. THE CLOCK IS TURNED ON BY LOGICALLY 
ENABLING THE INTERRUPTS TO CAUSE SOME ACTION OTHER THAN THE 
RESETTING OF THE TIMER FLIP-FLOP. 
*/ 

RQSTRC: PROCEDURE PUBLIC; 
TIMERSENABLED = TRUE; 
END RQSTRC; 



/* PUBLIC PROCEDURE: RQSTPC 

THIS PROCEDURE IS THE USER-CODED ROUTINE THAT DISABLES THE TIMER 
INTERRUPT LOGICALLY, WHICH WILL PREVENT ANY ACTION OTHER THAN THE 
RESETTING OF THE TIMER FLIP-FLOP. 
*/ 

RQSTPC: PROCEDURE PUBLIC; 
TIMERSENABLED = FALSE; 



END RQSTPC; 



END; 



APPENDIX H 
SYSTEM DEADLOCK 



A problem that may arise in multitasking systems, including those based on 
RMX/80, is deadlock — or, as it is sometimes called, the "deadly embrace." This 
situation occurs when each of a group of tasks is waiting for a resource that is being 
held by another task in the group. The result is a "circular wait" — the tasks in the 
group are all waiting for each other, and therefore all will wait indefinitely. The 
group of tasks is thus effectively "dead." 

For example, assume that two tasks, X and Y, in an RMX/80 system each require 
both the services of a high-speed math board (driven by a user-written handler task) 
to perform a set of arithmetic operations and analog I/O services provided by a 
single analog input/output board. The board that performs the arithmetic calcula- 
tions and the board that performs the analog input and output are both single-user 
resources — i.e., resources to which only one task can have access at any given time. 
This exclusive access is ensured by setting up an exchange at which a token message 
is available when the resource is not in use. A task wishing to use the resource waits 
at this exchange and receives the token message; when that task is finished with the 
resource, it sends the token message back to the exchange. Any other task requesting 
use of the resource must wait at the exchange until the first task returns the token 
message. (This is the technique discussed in Chapter 3 under "Exclusive Access to 
Code.") 

In our example, let exchange A control access to the math board, and exchange B 
control access to the analog input/output board. A programmer not concerned with 
the possibility of deadlock might code the two tasks in the following manner: 

Task X Task Y 

(high priority) (low priority) 

ADRA = RQWAIT (.A,0); ADRB = RQWAIT (.B,0); 

(perform calculations) (perform analog input) 

ADRB = RQWAIT (.B,0); ADRA = RQWAIT (.A,0); 

(perform analog input and output) (perform calculations) 



CALL RQSEND (.B.ADRB); CALL RQSEND (.A, ADRA); 

(perform calculations) (perform analog output) 

CALL RQSEND (.A, ADRA); CALL RQSEND (.B.ADRB); 



If, in the course of processing, task X is waiting at exchange B and task Y subse- 
quently waits at exchange A, each task will be waiting for a resource (a token 
message) held by the other task, and there will be a deadlock. Note that these tasks 
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may run correctly for a long period of time before this situation arises; but once it 
does occur, the two tasks are "dead" forever. 

One way to prevent this problem is to write the tasks so that no task ever holds one 
resource while waiting for another; i.e., each task has access to only one resource at 
a time. Tasks X and Y could be rewritten as follows: 



TaskX 
ADRA = RQWAIT (.A,0); 



Task Y 
ADRB = RQWAIT (.B,0); 



(perform calculations) 



(perform analog input) 



CALL RQSEND (.A, ADRA); 



CALL RQSEND (.B,ADRB); 



ADRB = RQWAIT (.B,0); 



ADRA = RQWAIT (.A,0); 



(perform analog input and output) 



(perform calculations) 



CALL RQSEND (.B,ADRB); 



CALL RQSEND (.A, ADRA); 



ADRA = RQWAIT (.A,0); 



ADRB = RQWAIT (.B,0); 



(perform calculations) 



(perform analog output) 



CALL RQSEND (.A.ADRA); 



CALL RQSEND (.B.ADRB); 



However, in some cases this solution — allowing each task access to only one 
resource at a time — may not be desirable or even feasible. Another, more generally 
applicable, solution is to write the tasks so that they request the resources in the 
same order — for instance, always A first, then B: 
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TaskX 



Task Y 



ADRA = RQWAIT (.A,0); 



ADRA = RQWAIT (.A,0); 



(perform calculations) 



ADRB = RQWAIT (.B,0); 



ADRB = RQWAIT (.B,0); 



(perform analog input) 



(perform analog input and output) 



(perform calculations) 



CALL RQSEND (.B,ADRB); 




.A, ADRA); 



(perform c 




CALL RQSEND (.A, ADRA); 



CALL RQSEND (.B.ADRB); 



When the tasks are written in this manner, a deadlock situation cannot occur, no 
matter where tasks A and B are in their processing at any given time. 

It can be shown that this method 1 can be extended to any number of tasks, the rule 
being that all tasks in a group that shares the same set of resources must request 
those resources in the same order. If some tasks release some resources before re- 
questing others, it suffices to follow this scheme: 

1. First, list all resources in some order. (You may order them in any way that is 
convenient or efficient in your system.) 

2. When coding tasks that request any of these resources, always follow the rule 
that a task may never request one resource when it already has access to (i.e., 
holds the token message for) any resource that precedes the requested resource 
on your list. For instance, if you list your resources in the order A, B, C, D, a 
task may not request resource B while it holds the token for A; it may not re- 
quest C while it holds the token for A and/or B; and it may not request D 
while it holds the token for A, B, and/or C. 

There is a cost associated with this solution to the deadlock problem, in that a task 
may be required to hold onto a resource much longer than it actually needs it. For 
instance, in our illustration with tasks X and Y, suppose that the analog input and 
output operations take a considerable amount of time, while the arithmetic calcula- 
tions take a relatively short time. The rewriting of task Y to follow the "order of re- 
quests" rule requires that task Y hold resource A (the math board) for the entire 
time needed to perform its analog input and output using resource B. 

Note, however, that in such a situation we can recode both task X and task Y to re- 
quest resource B before requesting resource A. The order (A before B) is probably 
appropriate if the use of resource B is for short periods of time and/or other tasks 
require the use of B and not of A. 

In systems where this solution proves inefficient, there are other methods to prevent 
deadlock, or alternatively, to detect and recover from it. Coffman, Elphick, and 
Shoshani' discuss the ordering method described here, plus a number of other solu- 
tions. 



'Coffman, E.J., Jr., M.J. Elphick, and A. Shoshani, "System Deadlocks," Computing Surveys , Vol. 3, 
No. 2, June 1971, pp. 67-78. 
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The RMX/80 Executive diskettes include all software for a Demonstration System 
which uses the full input-output Terminal Handler, Free Space Manager, and active 
Debugger, and adds a simple command line interpreter. The command line inter- 
preter supports a few simple commands, entered from the terminal, that allow you 
to request certain functions from the Fre; Space Manager. You can use the Debug- 
ger to observe what is happening in your system. 

The primary purpose of this system is to help you check out your hardware con- 
figuration to ensure that it operates correctly with RMX/80. Once you have the 
Demonstration System running properly you can proceed to test your application 
tasks with confidence that any errors found are the fault of the application software, 
not of your hardware. The Demonstration System is also useful in giving you 
"hands-on" familiarity with the Term nal Handler, Free Space Manager, and 
Debugger. It is suggested that all new RMX/80 users load and experiment with the 
Demonstration System before attempting to install an application system. 



Loading and Starting the Demonstration System 

The Demonstration System requires less than 21K bytes of code space (less than 20K 
for iSBC 80/20 and 80/10 versions) and less than 6K bytes of data space. It can run 
in one of two ways: in Intellec mapped memory via ICE-80 or ICE-85, or in memory 
in your system. Note that to run the Demonstration System from iSBC, memory ex- 
pansion boards are required. 



For iSBC 80/ 10 based systems, the Demonstration System supports the use of the 
clock hardware on an iSBC 104, 108, 116, or 5 1 7 combination expansion board, and 
a terminal with a transmission rate of 2400 baud. If you have an 80/ 10 system and 
your terminal's transmission rate is other ihan 2400 baud, you must set up the system 
for the proper baud rate. To accomplish this, use the Interactive Configuration 
Utility, with the file DEMOl.CON as a guide, then re-generate the system with the 
SUBMIT file produced by the ICU80 utility. 

Running in Intellec Mapped Memory via ICE-80 or ICE-85 

The RMX/80 Executive diskettes prov de an ISIS-II SUBMIT file (LOADX- 
.CSD) that loads the Demonstration System automatically via ICE-80 or 
ICE-85. This SUBMIT file is used when you wish to use Intellec memory in 
place of iSBC memory. The instructions that follow tell how to start up and 
run the Demonstration System using ICE. 

1. Set up your hardware configuratior , which must include a terminal for your 
iSBC system (in addition to the Intellec terminal used by ISIS-II and ICE). For 
installation instructions, refer to Appendix F and to the appropriate hardware 
installation manuals for your equipment. 

2. Start up your system hardware arid the Intellec system as directed in the 
appropriate hardware operator's manuals. 

3. Insert an ISIS-II system diskette (including ICE-80 or ICE-85) in drive of 
your Intellec system, and your RMX/80 Executive diskette in drive 1 . 
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4. Start ISIS-II as directed in the ISIS-II User's Guide (9800306). 

5. For iSBC 80/20 and 80/10 systems, set the ICE-80 mode selection switch on 
your system to LOAD. 

6. Give the ISIS-II command SUBMIT :Fl:LOADX (where X is 1 for iSBC 
80/ 10 systems, X is 2 for iSBC 80/20 systems, X is 3 for iSBC 80/30 systems, 
and X is 24 for iSBC 80/24 systems). The system will respond by displaying the 
commands in the SUBMIT file as tney are executed. Wait a few minutes until 
the line *LOAD :Fl:DEMO appears, followed by a line ending in a control-E 
prompt. 

7. For iSBC 80/20 and 80/10 systems, set the ICE-80 mode selection switch to 
RUN. 

8. Give the ICE-80 or ICE-85 command GO FROM 0. 

9. If your system is an iSBC 80/20 or 80/30, initialize the baud rate on your 
RMX/80 terminal by typing a series of U's, as described in Chapter 4 under 
"Automatic Baud Rate Search." When the rate is properly initialized, the 
following line will be displayed (followed by a carriage return): 

RMX/80 COMMAND LINE INTERPRETER, Vn.n 

where n.n is the version number of your RMX/80 software. On an 80/10- 
based system, this line should be displayed automatically after step 8 is per- 
formed, without any need to initialize the baud rate, provided you have set up 
the Demonstration System for the proper baud rate as directed at the begin- 
ning of this section. 

10. You may now enter Demonstration System commands, which are described 
later in this appendix, to communicate with the Free Space Manager. Note that 
since the Demonstration System runs under the control of the Terminal 
Handler, all Terminal Handler control character commands are active, and 
you may invoke the Debugger as usual. (Refer to Chapters 4 and 6 for details.) 

1 1 • When you are finished with the Demonstration System, you may use either the 
Intellec system interrupt 4 to return to ICE-80 or the ESCape key to return to 
ICE-85, then control-E to exit the submit file to return to ISIS-II. 

Running in PROM 

To run the Demonstration System in PROM, proceed as follows: 

1. Program your PROMs with the code from the file DEMO on the RMX/80 
Executive diskette. 

2. Install the PROMs starting at address on your system. 

3. Set up your hardware configuration, which must include a terminal for 
RMX/80, in accordance with Appendix F and the appropriate hardware in- 
stallation manuals for your equipment. 

4. Start up your system hardware and press RESET. 

5. For iSBC 80/20 and 80/30 systems, initialize the baud rate as in step 9 of the 
procedure given for running in mapped memory. 

6. Step 10 of the mapped memory operating procedure now applies. 
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Demonstration System Commands 

General Instructions 

The Demonstration System provides four commands for communication with the 
Free Space Manager. To enter a command, type the command name, a space, the 
parameter, if any, and a carriage return. As mentioned earlier, the Demonstration 
System operates under the Terminal Handler, so all Terminal Handler control com- 
mands are active. The Debugger may be invoked with a control-C. 

The parameters in the GET and PUT coir mands may be entered in decimal, hex- 
adecimal, binary, or octal; non-decimal numbers must include the appropriate suf- 
fix (H for hexadecimal, B for binary, O or Q for octal) following the rightmost digit. 
The Demonstration System gives responses in hexadecimal (without the H suffix). 

When the system is started or RESET, the Demonstration System initializes the Free 
Space Manager, so memory is immediately ivailable for allocation. 

Command Descriptions 



GET Command. GET allocates a block of RAM from the Free Space Manager. 
The format is as follows: 

GET size 

The GET command name may be abbreviated as G. Size must specify the length (in 
bytes) of the message to be allocated, whici must be a multiple of four bytes. If no 
parameter is given, a size of 8 (the minimum allocation) is assumed. 

If the Free Space Manager is able to mike the allocation, the system displays 
"FSSREQ" followed by the address and length of the allocated message in hex- 
adecimal. If the allocation request is too large and cannot be satisfied, the display in- 
dicates "FS$NAK" followed by the length of the largest available block of RAM. 



PUT Command. PUT returns a block of RAM to the Free Space Manager's pool. 
The format is as follows: 

PUT message-address 

The PUT command may be appreviated a 5 PU. Message-address specifies the ad- 
dress (usually in hexadecimal; be sure to include the 'H' suffix) of the message to be 
returned to the Free Space Manager. If the address is invalid, or if no address is 
given, the Demonstration System does not respond. 



POOL Command. POOL displays the locution and size of each block of free RAM 
in the Free Space Manager's pool. The format is as follows: 

POOL 

The POOL command may be abbreviated as PO. The command takes no 
parameters. 

For each block of free RAM, the system displays the word "POOL", followed (in 
hexadecimal) by the starting address and length (in bytes) of the block. If the pool is 
empty, nothing is displayed. 
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Two things should be noted about the Demonstration System's displays for the 
POOL command. First, two consecutive iterations of POOL often return responses 
that add up to the same amount of free RAM, but in different locations. This occurs 
because the Demonstration System's Command Line Interpreter task uses the Free 
Space Manager for allocation of a message in which to store the current command 
being entered from the terminal. Thus the operation of the Demonstration System 
itself affects the RAM pool. Second, POOL occasionally displays considerably less 
memory than should be available. This happens when the POOL task preempts the 
Free Space Manager's merge task (which runs at priority 254) while the merge task is 
in the process of combining two contiguous blocks of RAM. Since the merge task 
has temporarily removed the two blocks of RAM from the pool, the POOL com- 
mand will not display these blocks. If you give the POOL command again, the 
merge task should be finished, and the correct amount of memory should be 
displayed. 

MESSAGE Command. MESSAGE displays the list of messages allocated by the 
GET command and not yet returned by the PUT command. The format is as 
follows: 

MSG 

The MESSAGE command may be abbreviated as M. The command takes no 
parameters. 

For each currently allocated message, the system displays the text "MSG" followed 
by the starting address and length of the message. If no RAM is currently allocated 
to the user, there is no display. 
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APPENDIX J 
SYSTEM EXAMPLE 
A REAL-TIME CLOCK 



Introduction 

This appendix contains a complete, executable RMX/80-based system called 
RTCLOK (real-time clock). This extended example: 

f pulls together a number of RMX/80 concepts and facilities into a unified 
working system 

• is simple enough to be grasped by first-time RMX/80 users 

• implements a function that is relevant tc many applications 

" contains some useful routines that can be borrowed by RMX/80 users 

The point of the example is not to show how to implement a real-time clock with 
RMX/80. Instead, the real-time clock is used as a vehicle to illustrate basic RMX/80 
operations: sending and receiving messages, creating exchanges, using the Terminal 
Handler, and so on. 

The rest of the appendix is divided into threj sections. The first describes the exam- 
ple system from both external (what it does) and internal (how it does it) points of 
view. The second section provides some background on how the system was de- 
signed and tested; this information may be helpful to you as you develop your own 
approach to building RMX/80-based systerr s. The last section contains documenta- 
tion and source code listings for all the modules in the example. 



System Operation 

External 

RTCLOCK is fundamentally an expensive alarm clock. It uses a CRT terminal to 
display time of day and the setting of the alarm once per second like this: 

TIME=09:22:30-ALARM=10:00:00 

When the alarm "goes off," three exclamation points are appended to the display 
line and the terminal's audible alarm is sounded. Commands can be entered from 
the keyboard to: 

• suspend the time display 

• change the setting of the clock 

• change the setting of the alarm 

• request a "menu" display of valid comr lands 

The system is designed to run on an iSBC 80/20 and it determines the CRT's baud 
rate automatically. It could be modified to iun on an iSBC 80/30, or an iSBC 80/10 
with additional time base hardware. With a simple change, a hard-copy terminal 
could be used in place of the CRT. 

A typical terminal session illustrating the operation of RTCLOK is shown in figure 
J-1. Operator entries are shown in boldface, system displays in regular type. A car- 
riage return is indicated by (CR). 
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U (Terminal Handler baud rate search) 
RTCLOK: VERSION 1.0 

ALL TIMES ARE 24-HOUR FORMAT: HH:MM:SS 
09:22:30 = 9:22:30 AM 
17:30:00 = 5:30 PM 
00:00:00 = MIDNIGHT 
24:00:00 = NO TIME - CLOCK IS OFF 

AVAILABLE COMMANDS: 

C = SET REAL-TIME CLOCK 
A = SET ALARM 

? = DISPLAY THIS COMMAND MENU 
ENTERING A "NULL COMMAND" (CARRIAGE RETURN ONLY) SUSPENDS THE 
AUTOMATIC TIME DISPLAY. 

IF YOU ENTER C OR A, THE SYSTEM WILL PROMPT YOU TO ENTER A TIME. 
REMEMBER TO PUT IN COLONS. 

TO SHUT OFF THE ALARM, SET IT TO 24:00:00. 

TIME=24:00:00— ALARM=24:00:00 time displays write 
TIME=24:00:00— ALARM=24:00:00 over each other 
TIME=24:00:00— ALARM=24:00:00 on the same line. 

(CR) 
C(CR) 

HH:MM:SS? 
09:25:58 

TIME=09:25:59— ALARM=24:00:00 
TIME=09:26:00-ALARM=24:00:00 
A(CR) 

HH:MM:SS? 
09:26:10(CR) 

TIME=09:26:07— ALARM=09:26:10 

TIME=09:26:08— ALARM=09:26:10 

TIME=09:26:09— ALARM=09:26:10 

TIME=09:26:10— ALARM=09:26:10M! (bell sounds) 

TIME=09:26:11— ALARM=09:26:10M! (bell sounds) 
X(CR) 

INVALID COMMAND 

AVAILABLE COMMANDS: 

C = SET REAL-TIME CLOCK 

A = SET ALARM CLOCK 

? = DISPLAY THIS COMMAND MENU 
ENTERING A "NULL COMMAND" (CARRIAGE RETURN ONLY) SUSPENDS THE 
AUTOMATIC TIME DISPLAY. 

IF YOU ENTER C OR A, THE SYSTEM WILL PROMPT YOU TO ENTER A TIME. 
REMEMBER TO PUT IN COLONS. 

TO SHUT OFF THE ALARM, SET IT TO 24:00:00. 



Figure J- 1. RTCLOK Terminal ! 
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Internal 

Figure J-2 provides an overview of RTCLOK's RMX/80 structure. There are three 
user tasks: ONESEC, CONSOL and UPTIME. 
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Figure J-2. RTCLOK: Simplified Structure 



ONESEC sends a message to UPTIME every second to indicate the passage of time. 
CONSOL sends messages to UPTIME in response to commands received from the 
terminal. CONSOL also sends messages to the CRT via the RMX/80 Terminal 
Handler. UPTIME processes the messages it receives from CONSOL and ONESEC, 
and as a result, may send messages to the < 



Figure J-3 illustrates RTCLOK in more del ail. Tasks are shown as before; exchanges 
and message names have been added. Notice that the Terminal Handler is depicted 
as a "black box" — its own tasks, internal exchanges and messages are not shown. 
This is partly for clarity, but it also reflects a user task's "view" of the Terminal 
Handler — what goes on "inside" is of no concern to a user task. Five additional 
Terminal Handler exchanges are drawn with dashed lines: RQWAKE, RQALRM, 
RQDBUG, RQL7EX and RQL6EX. These exchanges are not used by RTCLOK, 
but are shown in the figure because they must be included in the configuration 
module of any system that uses the Terminal Handler. 



ONESEC waits at the WAITX exchange for 20 system time units (50 milliseconds 
each, one second total). Since no messages are ever sent to the WAITX exchange, 
ONESEC always receives a system message (TYPE=3H=TIME$OUT$TYPE) at the 
end of one second. It then sends an ADVANCESTIME message to the UPTIMX ex- 
change, signalling UPTIME to move the clock ahead one second. ONESEC then 
waits for another second, sends another ADVANCESTIME message, and so on in- 
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CONSOL sends a COMAND message to the Terminal Handler input exchange 
(RQINPX) to request an input line from the terminal. It waits for a response from 
the Terminal Handler at the response exchange called CREADX. When the Ter- 
minal Handler returns the COMAND message to CREADX, CONSOL calls a 
routine to process the command contained in the message. CONSOL uses a message 
called REPLY to provide feedback to the operator. Whenever it sends the REPLY 
message to RQOUTX (the Terminal Handler output exchange), CONSOL waits at 
CWRITX until the Terminal Handler has finished writing the message line to the 
display. After it has processed a command, CONSOL again sends the COMAND 
message to the RQINPX exchange and waits for the operator to enter the next com- 
mand. This process continues indefinitely. 

CONSOL can send two messages to UPTIME, via the UPTIMX exchange. These 
are triggered by commands entered by the terminal operator. The 
ENABLESDISPLAY message instructs UPTIME to start or stop the automatic time 
display (message TYPE=140 starts the display and TYPE=130 stops it). The display 
is suspended upon request from the operator (a carriage return only is entered), 
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Figure J-3. RTCLOK: System Structure/Message Flow 
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when the operator is responding to a query from CONSOL, and whenever CONSOL 
is sending a series of messages to the terminal. Suspending the time display like this 
prevents different messages from becomiig interspersed with each other and with 
echoed operator entries on the display. The real-time clock keeps running, however, 
regardless of whether it is being displayed. 

The other message that CONSOL sends to UPTIME is SETSTIME. If this message 
has a TYPE of 1 10, UPTIME is to change the setting of the alarm to the value con- 
tained in the text of the message. If the SETSTIME message's TYPE is 120, UP- 
TIME is to use the value in the message to >et the real-time clock instead. 

UPTIME maintains the real-time clock in response to messages received from CON- 
SOL and ONESEC. UPTIME waits for a message at the UPTIMX exchange. If the 
message is ENABLESDISPLAY, UPTIME turns the automatic time display on or 
off. If the message is SETSTIME, UPTIME sets the alarm or the real-time clock. If 
the message is ADVANCESTIME, UPTIME moves the clock ahead one second 
and, if the display is currently enabled, d splays the new time and alarm setting by 
sending the SHOWSTIME message to the Terminal Handler output exchange 
RQOUTX. Before sending the message, UPTIME compares the values of the real- 
time clock and the alarm. If the alarm should be "ringing," UPTIME adds three ex- 
clamation points and two BEL characters to the SHOWSTIME message. The BEL 
characters will cause the terminal's audible alarm to sound, if it has one. 



Development Background 

RTCLOK was developed in steps, following a conventional sequence: 

• defining requirements 

• designing the system 

• coding the modules 

• linking and locating the modules 

• testing the system 

What "went on" in each of these steps is tr e subject of this section. 
Defining Requirements 

RTCLOK's requirements were identified as follows: 
Functions 

• keep time with one second resolution 

• indicate if time >= alarm 

• allow clock and alarm to be set from console 

• display time and alarm automatically 

• suspend automatic time display upon request 

• reject invalid operator entries 

Events 

• operator enters data 

• one second passes 
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Constraints 

• simple task/exchange/message structure 

• to avoid losing time, a task mus: be waiting whenever the RMX/80 clock 
"ticks" (every 50 msec.) 

Hardware 

• iSBC 80/20 

• CRT terminal 

Designing the System 

The design activity transformed the system requirements into an RMX/80 
task/message/exchange structure and a module (program) structure. 

First a general design was produced, resulting in the system as depicted in figure 3-2. 
This helped to delineate tasks and their priorities. The system requirements were 
grouped into logically related clusters that might be implemented as a few coherent 
RMX/80 tasks. The groups that evolved were: 

• interact with the operator via the console (terminal). 

• maintain and display the clock. 

• wait for one second. 

These became the CONSOL, UPTIME (update time) and ONESEC tasks. Why 
wasn't ONESEC combined with UPTIME? A single task could easily perform the 
one second wait and still display the clock and alarm settings between clock ticks. A 
problem might arise, though, if this task also had to process requests to start/stop 
the display and reset the clock and the alarm. These requests occur unpredictably 
(asynchronously), usually in response to operator entries. It is true that the operator 
can only enter a few such requests compared to the system's processing speed, and it 
is likely that all such requests could be handled between clock ticks. However, this 
approach would complicate the design and would be limiting. What if other tasks 
were added to the system that requested time information? It was definitely a ques- 
tion of judgment, but it seemed simpler to separate the "wait for one second" re- 
quirement from the "maintain and display time" requirement. In general, allocating 
different, or loosely related, functions to separate tasks yields the best design. 

Priorities were assigned to the three tasks according to the "criticality" of their 
functions. Clearly, the system would lose its integrity (would not keep accurate time) 
if it missed a clock tick, so ONESEC was given the highest priority. (In addition, 
ONESEC takes so little time to execute that its high priority would not interfere with 
lower priority tasks.) On the other hand, the task that could best afford to be 
delayed during periods of high loading (as unlikely as this might be in a system as 
simple as RTCLOK) was CONSOL: operator commands would be relatively infre- 
quent events in the first place, and responses could be delayed for fairly long (say a 
second or two) periods without unduly inconveniencing the operator. This left UP- 
TIME with a middle priority which seemed appropriate for its needs: having a 
higher priority than CONSOL insured that UPTIME would be able to "keep up" 
with the messages sent by CONSOL. Note that difficulty in assigning priorities can 
be a sign of improper task definition; usually a task needs to be subdivided into tasks 
with different priorities. 

The priorities of all the tasks (ONESEC: 130, UPTIME: 160, CONSOL: 180) are 
lower than the RMX/80 software priorities that correspond to hardware interrupt 
levels (0-128). None of the tasks services a hardware interrupt; keeping them out of 
the hardware interrupt range insures that they will not interfere with tasks like the 
Terminal Handler that must respond to hardware requests for service. 
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ONESEC will not be appreciably delayed by the Terminal Handler, even though it 
has a lower priority. This is because the Terminal Handler works with one character 
of message text at a time. It relinquishes control of the system (waits) between 
characters, giving ONESEC the opportunity to run if it is ready. 

RTCLOK's exchange structure was largely dictated by the nature of the system's 
tasks. The RMX/80 Terminal Handler performs all housekeeping involved with ter- 
minal I/O. Therefore terminal input is obtained by CONSOL from the RQINPX 
Terminal Handler exchange. Likewise, output displays generated by CONSOL and 
UPTIME are sent to the Terminal Handle - output exchange RQOUTX. In order for 
ONESEC to time out at one-second intervals, it needs to wait at an exchange to 
which no messages are ever sent; the WAITX exchange is dedicated to this single 
use. Whenever CONSOL or ONESEC want UPTIME to "do something" to the 
clock, the alarm, or the time display, they send a message to the UPTIMX exchange. 
Queuing these various types of messages at a single exchange is appropriate for UP- 
TIME because it deals with fairly low message rates. One message per second arrives 
from ONESEC, and a few messages come from CONSOL each time the operator 
makes an entry. What if, however, CONSOL were capable of sending bursts of, say, 
100 messages per second? ONESEC assumes that UPTIME has processed the 
previous ADVANCESTIME message and reuses the RAM area each second. Having 
to process an intervening burst of messages from CONSOL could well cause UP- 
TIME to miss an ADVANCESTIME message, thereby causing the clock to lose one 
second. In a situation like this it would be better to split UPTIME into separate 
tasks, one to handle messages from CONSOL and one to service messages from 
ONESEC. 

After the general design depicted in figure J-2 was verified against the system re- 
quirements and subjected to a mental "simulation" of operation, the design was ex- 
panded to the more detailed structure shown in figure J-3. Response exchanges were 
added to coordinate interaction with the Terminal Handler. A task that sends a 
message to the Terminal Handler must not modify the message or send it again until 
the Terminal Handler is through with the message. The Terminal Handler returns 
the message to the exchange specified ir the message's Response Exchange field 
when it has completed the requested operation. Therefore, CONSOL and UPTIME 
wait at response exchanges until they receive acknowledgement from the Terminal 
Handler that the previously sent message can be reused. 

Unused, but required, Terminal Handler exchanges were also defined at this time to 
be sure that they were included in the conf guration module. 

Finally, messages were named and their contents defined. To keep the number of 
messages (and consequently RAM requirements) to a minimum, some messages are 
used for more than one function. For example, the same message (SETSTIME) is 
used to instruct UPTIME to set the alarm or the clock ( the functions are 
distinguished by different TYPE codes). Using this technique requires special care. 
With two different "versions" of the sam: message (i.e., the same RAM area), a se- 
cond version of a message can overwrite a previous version that has not yet been 
processed by the receiving task. This cannot happen in RTCLOK because UPTIME 
runs at a higher priority than CONSOL. Every time CONSOL sends a message to 
UPTIME, UPTIME becomes the running task and processes the message. Alter- 
natives to this approach include using the Free Space Manager to obtain and release 
RAM areas for the different versions and using response exchanges to coordinate 
message reuse. 

A module is a segment of code that can be assembled or compiled as an individual 
unit. Designing RTCLOK's module structure was simple because RMX/80 does not 
restrict module definition in any way. An RMX/80 task is a public procedure. 
Multiple tasks can be combined into a single module or a single task may consist of 
multiple modules. For that matter, the configuration "module" does not even have 
to be a module. In general, it is good practice to code each task as one or more 
modules and the configuration module as one module. 
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RTCLOK was divided into modules as follows: 



Task 

ONESEC 
UPTIME 
CONSOL 



Modules 



ONESEC 

UPTIME.NUMOUT 
CONSOL,SCANIN 



The configuration module was coded as a sixth module called RTCLOK. NUMOUT 
and SCANIN had already been implemented as modules for another (non-RMX/80) 
system and were incorporated without change. Note that each of these procedures is 
called by only one task. If these procedures were to be shared among tasks, software 
lockouts or reentrant coding as described in chapter 3 would have been required. 

Coding the Modules 

All modules were written in PL/ M-80, so long as an interrupt does not occur at any 
of the corresponding hardware interrupt levels, RMX/80 does not attempt to refer- 
ence these exchanges and the unresolved external messages (see chapter 3) can be 
ignored. However, by not having the message issued routinely every time the system 
is linked, a "real" unresolved message may be more noticeable if it is issued by the 
Linker. If an unexpected interrupt for one of these exchanges does occur, the 
exchange will be referenced and the result will almost certainly be catastrophic to the 
system. This is true whether the references are "tied off" as above or not. 

Stack space allocations for the tasks were based on the numbers provided by the 
PL/M-80 compiler, plus the largest stack needed by an RMX/80 Nucleus operation, 
(see appendix A) plus 24 bytes for RMX/80 to use in a context save. 

ONESEC<2) + RQWAIT(4) + RMX/80(24) - 30 bytes 

UPTIMEO0) + NUMOUT(6) + RQWAIT(4) + RMX/80(24) = 44 bytes 

CONSOL(8) + SCANIN(4) + RQWAIT(4) + RMX/80(24) = 40 bytes 

The Debugger Format Task and Scan commands were used during testing to verify 
that the stacks were not overflowing. 

An alternative to setting stack lengths is to make them intentionally too large at first 
and then use the Debugger to see how much of the space is actually used in execu- 
tion. A useful aid in this approach is that the Format Task command tells the 
number of bytes of the allocated stack space that have not yet been used. Assuming 
that you can establish worst-case conditions, this command would enable you to 
determine a stack's maximum possible depth. 

ONESEC, CONSOL and UPTIME are patterned after the general RMX/80 "task 
model." A public procedure is defined with the name of the task. The procedure 
begins with a section of initialization code. This creates exchanges used by the task 
(and not already created by earlier users of the exchange), initializes constant por- 
tions of messages, sets switches to their initial values, etc. This initialization code is 
only executed when RMX/80 restarts the system. After executing the initialization 
code, control falls into an endless loop. This loop contains the main processing logic 
of the task. CONSOL, for example, waits for a message, processes the message, 
waits for another message, and so on indefinitely. Execution of this loop will be 
stopped (usually temporarily) if any of the following happen: 

• an interrupt occurs, causing a higher priority task to become ready (this task can 
in turn cause additional higher priority tasks to become ready) 

• a higher priority task in a timed wait times out and thus becomes ready 

• the running task sends a message to an exchange where a higher priority task is 
waiting, thus making it ready 

• the running task enters a timed wait or waits at an exchange where no message is 
queued 

• the running task deletes or suspends itself 



J-8 



RMX/80 



System Example: A Real Time Clock 



In the first two cases, the task is preempted by another task, and RMX/80 saves the 
task's registers on the stack (performs a context save). In the last three cases, the 
task surrenders control of the processor and the registers are not saved. 



The following is the dialogue carried out with the Interactive Configuration Utility. 
The result of this dialogue is a SUBMIT file which, when SUBMITted, causes the 
RTCLOK system to be linked and located, producing a ready-to-run system. 

CONFIG: :F1:RTCLOK.CNF 
SUBMIT: :F1:RTCLOK.CSD 
CAM: :F1:RTCLOK.CAM 
LINKOBJ: :F1 :RTCLOK.LNK 
LINKMAP: :F1 :RTCLOK.LEM 
LOCOBJ: :F1:RTCLOK 
LOCMAP: :F1:RTCLOK.LOM 
CAMOBJ: :F1:RTCLOK.LOC 
CAMMAP: :F1 :RTCLOK.CLM 
BOOT LDR: NO 
LOADABLE: NO 
SBC TYPE: 80/20 

SYSTEM TIME UNIT: 50 
TERM HNDLR: FULL 

FUNCT: I/O 

RATE: SEARCH 

CNTL TBL: NO 

THISTK: 46 

THIPRI: 112 
CMND LINE INTRPTR: NO 
FSM: NO 
DEBUG: ACTIVE 

DBGSTK: 64 

DBGPRI: 50 
ANLG HDLR: NONE 
TASK NAME: CONSOL 

ENTRY POINT: CONSOL 

STK LENGTH: 42 

PRIORITY: 180 

DFLT EXCHG: 

TASK DESCRIPTOR NAME: 

EXTRA BYTES: 
TASK NAME: UPTIME 

ENTRY POINT: UPTIME 

STK LENGTH: 44 

PRIORITY: 160 

DFLT EXCHG: 

TASK DESCRIPTOR: 

EXTRA BYTES: 
TASK NAME: ONESEC 

ENTRY POINT: ONESEC 

STK LENGTH: 30 

PRIORITY: 130 

DFLT EXCHG: 

TASK DESCRIPTOR NAME: 

EXTRA BYTES: 
TASK NAME: *** 
EXCHANGE: *** 
DFS: NO 
BASIC: NO 
FORTRAN: NO 
NUCLEUS: :F1: 
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EXTENSIONS: :F1: 
LINK: :F1:SCANIN.OBJ 
LINK: :F1:ONESEC.OBJ 
LINK: :F1:CONSOL.OBJ 
LINK: :F1:UPTIME.OBJ 
LINK: :F1:NUMOUT.OBJ 
LINK: *** 
CODE: 

DATA: RELOCATABLE 



Testing the System 

RTCLOK was tested with the aid of ICE- 80 (see In/Circuit Emulator/80 Operator's 
Manual, 9800185) and the RMX/80 Active Debugger. ICE-80 allowed the program 
to be executed from Intellec RAM, eliminating the need to program PROMs for the 
iSBC 80/20. It also allowed controlled execution of the program using breakpoints, 
and examination of intermediate results in memory. The Debugger was used 
primarily to monitor stacks; however, it could have been used to set breakpoints and 
examine memory if ICE-80 had not been available. 

The following SUBMIT file was used to load RTCLOK into Intellec memory and 
begin emulation (execution under the control of ICE-80): 

ICE80 
BASE HEX 

XFORM MEMORY INTO 6 
XFORM MEMORY 1 INTO 7 
XFORM MEMORY 2 INTO 8 
XFORM MEMORY 3 INTO 9 
XFORM MEMORY 4 INTO 10 
XFORM MEMORY 5 INTO 11 
XFORM MEMORY 6 T0 15 GUARDED 
XFORM IO0 TO 15 UNGUARDED 
LOAD :F1 :RTCLOK 

The first step in testing, however, was to verify that the hardware (iSBC 80/20 and 
CRT terminal) was set up properly. This was done by loading and executing the 
Demonstration System supplied with RMX/80 and described in appendix I. Suc- 
cessful execution of this system meant that subsequent difficulties in testing 
RTCLOK could probably be attributed to software errors, rather than hardware 
problems. 



RTCLOK was tested incrementally, adding one task at a time. This technique 
simplifies debugging because it usually isolates the source of error to one task, or to 
the interaction of two tasks. For systems larger than RTCLOK, incremental 
development can profitably be extended to design and coding as well. This allows 
different techniques to be tested with quick feedback. A few tasks can be designed, 
coded and tested, and the knowledge gained from this experience can be used in the 
development of the rest of the system. Note that the RMX/80 Debugger contains a 
number of features that complement incremental development. 

Incremental testing necessitates making temporary changes to some tasks that 
reference tasks and data not yet linked into the system. For example, when CON- 
SOL was tested by itself, references to UPTIME were "commented out" like this: 

/****CALLRQSEND(.UPTIMX,.SET$TIME);****/ 
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Configuration was performed again as new tasks were added to the test system. 



CONSOL was tested first with no other tasks in the system except the Terminal 
Handler. This verified that the configuration module was correct and that messages 
were being sent to and received from the lerminal properly. (In its first test run, the 
system did not come up at all. The error was, as it often is in cases like this, in the 
configuration module.) Messages that CONSOL sent to UPTIME were examined 
with ICE-80 to insure that they were being constructed properly. 

Next UPTIME was linked in so that the interaction between CONSOL and UP- 
TIME could be checked out. UPTIME'; automatic time display was temporarily 
modified to display the time whenever any message was received rather than just 
when ADVANCESTIME arrived from ONESEC (which was not yet in the system). 

Finally ONESEC was added. To simpliiiy monitoring the system, ONESEC was 
temporarily changed to issue ADVANCE ISTIME every five seconds instead of every 
second. 



Structure Charts and Source Code Listings 

The following pages contain two structure charts, an ICU80 dialogue, and the 
compiled source code for each of RTCLOK's five modules. A structure chart, as it is 
used here, is a modification of the concept of flow chart. Because most tasks consist 
of an initialization phase followed by an endless loop, it is convenient to have a 
pictorial device that reflects this nicely. 1 1 figure J-4, the name of the task appears 
first, then the initialization phase, after which the "main routine" is first shown, for 
emphasis, as a single box with "do forever"; the detail of the main routine is seen 
below the "main routine" box, and it flows from left to right. Thus, the "do forever" 
part of ONESEC is: wait, send, wait, send, etc. The other tasks, depicted in figures J- 
5 and J-6 are to be read similarly. 



ONiiSEC 






INIT ALIZE 




1 


M 

ROl 


MN 
TINE 



DO FOREVER 



WAIT 
FOR 
1 SECOND 



SEND 
ADVANCESTIME 
MESSAGE 
TO UPTIME 



Figure J-4. ONESEC Structure Chart 
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Figure J-5. UPTIME Structure Chart 
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CONSOLE 



INITIALIZE 



6 <h 



DO FOREVER 



WAIT FOR 
COMMAND 
MESSAGE 



SI 
REAL 

CLC 


.T 

TIME 
CK 






BUILD 
SETSTIME 
MESSAQE 
(TYPE = 120) 



1 



REJECT 
INVALID 

TIME 
SETTING 



St 
ALfl 


T 

RM 








BUILD 
SETSTIME 
MESSAGE 
(TYPE = 110) 



SUPPLY 

TIME 
SETTING 



JscamnJ 



— I 1 — 

d)(£) 



VALIDATE TIME 
COMPLETE 
SETSTIME 
MESSAQE 



SEND 
SETSTIME 
MESSAGE 
TO UPTIME 



ASK 
FOR 
TIME 



SEND 
BADSTIMESMSG 
TOT.H. 



1 



TURN ON 
AUTO TIME 
DISPLAY 



DISPLAY 
VALID 
COMMAND 
MENU 



SEND 
TIMESMSG 
TOT.H. 



SEND 
ENABLESDISP 
(TYPE = 140) 
TO UPTIME 



1 



REJ 
INV 
COM 


ECT 
VLID 
/I AND 






DISPLAY 
INVALID 
COMMAND 



SHUT OFF 
AUTO TIME 
DISPLAY 



SEND 
MENUSMSG 
TOT.H. 



SEND 
INVALIOSMSG 
TOT.H 



SEND 
ENABLESDISP 
(TYPE = 130) 
TO UPTIME 



Figure J-6. CONSOL Structure Chart 
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mm.m . fi : r t clc*. ash debug 



ISIS-II 80S6,'S985 NflCRO ASSEMBLER, V2. 8 RTCLOK PAGE 1 

mtm. RHX/80 REAL-TIME CLOCK EXAMPLE 

LOC OBJ SES SOURCE STATEMENT 

1 ITITLECRTCLOK: RMX/88 REAL-TIME CLOCK EXAMPLE') 

3 i CONFIGURATION MODULE FOR REflL-TIME CLOCK EXAMPLE 

4 ; 

5 ; HARDWARE ASSUMPTIONS: 

6 ; COMPUTER IS ISBC 88/26 

7 i TERMINAL IS CRT 

8 i 

9 NAME RTCLOK 
18 CSEG 

11 i 

12 ; PICK UP MACRO DEFINITIONS 

13 i 

= 14 IINCLUDE (:F1.STD. MAC) 
= 15 .; 

s 16 i MRCRO TO BUILD STATIC TASK DESCRIPTOR (STD) AS 

■ 17 .; A COMPONENT OF THE INITIAL TASK TABLE (ITT). 

= 18 ; 

= IS i THIS MACRO ACCEPTS 4 PARAMETERS. 
= 28 i 

« 21 i CD THE NAME OF THE TASK ENTRY POINT. 

= 22 ; (2) THE SIZE (IN BYTES) OF THE STACK REQUIRED BY 

= 23 i THIS TASK. 

= 24 ; (3) THE PRIORITY OF THIS TASK. 

= 25 ; m THE DEFAULT EXCHANGE ADDRESS (IF ANY), TO BE 

■ 26 i USED WITH THIS TASK. 
= 27 i 

= 28 STD MACRO NAME.- STKLE4.. PPI, EXCH 

= 29 LOCAL TSTK 

= 38 EXTRN NAME 

= 31 IF NTASK EC! 8 

= 32 ITT: 

= 33 Bm 

= 34 DSEG 

= 35 TSTK. DS STKLEN 

» 36 CSEG 

« 37 IMOGEN NOCOMD 

= 33 mm MACRO Fl 

* 39 ADDCHR MACRO F2 

* 40 ADDCHR MACRO F3 
= 41 ADDCHR MACRO F4 

* 42 ADDCHR MACRO F5 
= 43 ADDCHR MACRO F6 
= 44 IGEH 

s 45 DB 'F1MF2MF3MF4MF5KF6- 

= 46 IMOGEN 

= 47 ADDCHR MACRO 

= 48 ENDM 

= 49 ENDM 

a 58 ENDM 

■ 51 ENDM 
= 52 ENDM 
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ISIS-II 8880/8685 MRCRO ASSEMBLER, V2. 
RTCLOK: mm REAL-TIME CLOCK EXAMPLE 



RTCLOK PAGE 



2 



LCC OBJ 



SEQ 



SOURCE STATEMENT 



= 53 ENDM 

= 54 ENDM 

= 55 IRPC CHAR, <NflHE > 

- ur.r.rijQ /ruflD^ 

= 57 ENDM 

« 58 $GEN 

= 59 DW NAME 

= 68 DW TSTK 

= 61 M STKLEN 

= 62 DB PRI 

= 63 DM EXCH+8 

= 64 DM TDBASE+<HTASK*28) 

= 65 NTflSK SET NTASK+! 

= 66 ENDM 

= 67 t INCLUDE < H XCHADR. MAC:) 



* 69 ; THIS MACRO WILL BUILD ONE 

= 78 ; COMPONENT OF THE INITIAL 

= 71 ; EXCHANGE TABLE (IET) EACH 

= 72 ; TIME IT IS INVOKED. 

« 73 j 

= 74 XCHADR MACRO NAME 

= 75 EXTPN NAME 

s 76 IF NEXCH EG 9 

= 77 IET: 

= 78 END IF 



DW NAME 



= 88 NEXCH SET NEXCH+1 
= 81 ENDM 



= 82 f INCLUDE ( :F1:GENTD. MRC) 

* 83 ; 

* 34 ; TASK DESCRIPTOR GENERATION MACRO FOR BUILDING STD 
» 85 i AND ITT. 

* 86 ; 

= 87 GENTD MACRO 

» 38 DSEG 

= 89 TD6RSE : DS 28*NTflSK 

■ 96 CSEG 

« 91 ENDM 

a 92 J INCLUDE (:F1:CRTAB. MAC) 

= 93 ; 

= 94 ; THIS HflCRO BUILDS THE R6CP1B TABLE. IT MUST 

= 95 : BE INVOKED AFTER THE STD m XCHADR MACROS 

= 96 ; IN ORDER TO WORK FROF'ERLV. 

= 97 ; 

- 98 CRTAB MACRO 
a 99 PUBLIC RQCRTB 

= 109 RQCRTB: 
= 101 DW ITT 

= 192 DB NTflSK 

= 183 DW IET 

= 184 DB NEXGH 

= 185 ENDM 

196 ; 

187 ; CLEAR TEMPS USED BV MACROS 
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ISIS-1I 8888/8885 MACRO ASSEMBLER, & 8 RTCLOK PAGE 3 

RTCLOK: RMX/88 REAL-TIME CLOCK EXAMPLE 

LOC OBJ SEC SOURCE STATEMENT 

188 i 

189 NT ASK SET 8 
118 NEXCH SET 8 

111 ; 

112 • TIE OFF REFERENCES TO UNUSED INTERRUPT EXCHANGES 







113 i 










114 


DSEG 




8882 




115 DUMREF 


DS 


2 






116 RQL8EX 


EQU 


DUMREF 


8888 


D 


117 RQL2EX 


E8U 


DUMREF 




b 


118 R6L3EX 


EQU 


DUMREF 


8888 


D 


119 RQL4EX 


ESU 


DUMREF 


8888 


D 


128 RQL5EX 


ECU 


DUMREF 






121 


PUBLIC RSL8EX, RQL2EX, RQL3EX, RQL4EX, RQL5EX 






122 ; 










123 i BUILD INITIAL TASK TABLE ENTRIES 






124 .. 










125 ; 


;PARfil€TERS : TASK.. STACKLENGTH, PRIORITV) 






126 ; 










127 


CSEG 








128 


STD CONSOL.42,188 






129+ 


EXTRN 


CONSOL 






138+ 


IF 


NTASK EQ 8 






131+ITT: 










132+ 


ENDIF 








133+ 


DSEG 




882A 




134+?^8881 


DS 


42 






135+ 


CSEG 




8888 434F4E53 




219+ 


06 


'CONSOL' 


8884 '4F4C 




+ 






8806 8880 


E 


238+ 


DH 


CONSOL 


80(38 0288 


i 


231+ 


DM 


778881 


080A 2A88 




232+ 


DH 


42 


008C B4 




233+ 


DB 


188 


808D 0008 




234+ 


DU 


+8 


800F DA80 


D 


235+ 


DM 


TD6ASE+<NTASK*28> 


0001 




236+NTASK 


SET 


NTASK+1 






237 


STD UPTIME, 44, 168 






238+ 


EXTRN 


UPTIME 






242+ 


DSEG 




882C 




243+'??88e2: DS 


44 






244+ 


CSEG 




8811 55505449 




328+ 


DB 


'UPTIME' 


0815 4D45 




+ 






0817 8880 


E 


339+ 


DM 


UPTIME 


0819 2C88 


D 


348+ 


DH 


??eee2 


8816 2C88 




341+ 


DH 


44 


881D A8 




342+ 


DB 


168 


331E 8008 




343+ 


DH 


+8 


0020 EE00 


D 


344+ 


DM 


TDBASE+<NrASK*28) 


0882 




345+NTASK 


SET 


NTASK+1 






346 


STD ONESEC,38,130 






347+ 


BCTRN 


ONESEC 






351+ 


DSEG 




881E 




352+?788e3: DS 


38 
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ISIS-I1 8888/8885 MACRO ASSEMBLER, V2 8 
RTC-LOK: RMX/86 REAL-TIME CLOCK. EXAHPLE 



LOC OBJ 



SEQ 



SOURCE STATEMENT 







353+ 


CSEG 




8822 4F4E4553 




437+ 


DB 


'ONESEC 


8826 4543 




+ 






8628 8888 


E 


448+ 


DH 


ONESEC 


3@2H 


D 


449+ 


DM 


??8ee3 


882C 1E88 




458+ 


DH 


38 


862E 82 




451+ 


DB 


138 


882F 8888 




452+ 


DM 


+8 


8631 8281 


D 


453+ 


DH 


TDBASE+<NTASK<28> 


8881 




454+NTASK 


SET 


HTRSK+1 






455 


STD 


PQTHDI,36,112 






456+ 


EXTRH 


RQTHDI 








DSEG 




8824 




461+'?8664 


DS 


36 






462+ 


CSEG 




8833 52515448 




546+ 


DB 


'RQTHOI 


8837 4449 




+ 






8839 8888 


E 


557- 


DH 


RQTHDI 


883E 7688 


D 


558+ 


DH 


r?eee4 


683D 2468 




559+ 


DH 


36 


863F 78 






DB 


112 






561+ 


DH 


+6 


8642 1681 


D 


562+ 


m 


TD8ASE+<NTASK»26> 


8884 




563+NTASK 


SET 


NTfiSK+i 






564 


STD 


poflreG..64,2ee 






565+ 


EXTRh 


RQflDBG 






569+ 


DSEG 








578+^^8885 


DS 


64 






571+ 


CSEG 




8644 52514144 




655+ 


DB 


'RQflDBG' 


8648 4247 




+ 






864A 6668 


E 


666+ 


DH 


RQflDBG 


864C 9A88 


D 


667+ 


DH 


''78885 


964E 4888 




668+ 


DH 


64 


8658 C8 




669+ 


DB 


288 


8851 8886 




678+ 


DH 


+8 


8853 2881 


D 


671+ 


DH 


tdbase+<nthsk*28> 


8885 




672+NTASK 


SET 


NTASK+1 



> TERMINAL HflNDLER 



; ACTIVE DEBUGGER 



8855 8888 E 

Often 



8857 8888 E 



8859 8888 E 
8883 



673 
674 
675 
676 ; 
677 
678+ 
686+IET: 
682+ 

683+NEXCH 
684 
685+ 
689+ 

698+NEXCH 
691 
692+ 
696+ 

697+NEXCH 



BUILD INITIAL EXCHANGE TABLE 

■USER EXCHANGES CREATED IN TASKS— NOT PRESENT IN IET) 

xchadp mum 

EXTRN RQINPX 



DH RQINPX 
SET HEXCH+1 

XCHRDR RQOUTX 
EXTRN RQOUTX 
DH RQOUTX 
SET NEXCH+1 

XCHftDR RQHflKE 
EXTRN ROMAKE 
DU ROHftKE 
SET NEXCH+1 
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ISIS-I I 8888/8885 MACRO ASSEMBLER, V2. RTCLOK PAGE 

RTCLOK: RMX/80 REAL-TIME CLOCK EXAMPLE 



LOC OBJ 



SEQ 



SOURCE STATEMENT 



TOJD tow 

ana a 



005D 0980 



0887 



8864 



8863 85 
0066 5509 
8868 87 



698 


.>!CHADP 


RQDBUG 


699+ 


EXTRN 


RQDBUG 


783+ 


DW 


KQDfciUu 


C84+NEXCH 


SET 


NEXCH+1 


785 


XCHADR 


RQALRM 


786+ 


EXTRN 


RQALRM 


718+ 


DW 


RQALRM 


711+NEXCH 


SET 


NEXCH+1 


712 


XCHADR 


RQL6EX 


713+ 


EXTRN 


RQL6EX 


717+ 


DW 


RQL6EX 


718+NEXCH 


SET 


NEXCH+1 


719 


XCHADR 


RQL7EX 


728+ 


EXTRN 


RQL7EX 


724+ 


DH 


RQL7EX 


725+NEXCH 


SET 


NEXCH+1 


726 ; 






727 ; ALLOCATE RAM FOR TASK DESCRIPTORS 


728 i 






729 


GENTD 




738+ 


DSEG 




731+TDBASE 


DS 


28*NTASK 


732+ 


CSEG 




733 i 






734 ; BUILD CREA 


rE TABLE 


735 > 






736 


CRTAB 




737+ 


PUBLIC RQCRTB 


738+RQCRTB: 




739+ 


DU. 


ITT 


748+ 


DB 


NT ASK 


741+ 


DW 


IET 


742+ 


DB 


NEXCH 


743 i 






744 i END OF RTCLOK CONFIGURATION MODULE 


745 ; 






746 


END 





PUBLIC SYMBOLS 
RQCRTB C 8063 



RQL8EX D 0888 RQL2EX D 8888 RQL3EX D 8888 RQL4EX D 8888 RQL5EX D 



EXTERNAL SYMBOLS 

CONSOL E 8688 ONESEC E 8888 RQADBG E 
RQL7EX E 8888 RQOUTX E 8088 RQTHDI E 



RQALRM E 6898 
RQWfiKE E 8688 



RQDBLIG E 8686 
UPTIME E i 



RQINPX E 8886 RSL6EX E 8888 



USER SYMBOLS 
ADDCHR + 8008 
NEXCH A 0007 
RQINPX E 0088 
RQL7EX E 8888 
XCHADR + 0888 



CONSOL E 6888 
NT ASK A 8885 
RQLOEX D 8888 
RQOUTX E 8888 



CRTAB + 6888 
ONESEC E 8088 
RQL2EX D 6068 
RQTHDI E 0006 



DUMREF D 8888 
RQADBG E 0000 
RQL3EX D 8886 
RQHAKE E 6888 



GENTD + 8065 
RQALRM E 8888 
RQL4EX D 8888 
STD + 8886 



IET C 
RQCRTB C 8863 
RQL5EX D 8888 
TDBASE D 88DA 



ITT C 8888 
RQDBUG E 8888 
RQL6EX E 8888 
UPTIME E 8880 



ASSEMBLY COMPLETE, NO ERRORS 
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PL 71-80 COMPILER SCANIN: RMX/86 REAL-TIME CLOCK I SAMPLE PAGE 1 



ISIS-II PL/M-80 V3.1 COMPILATION OF MODULE SCftNIN 
OBJECT MODULE PLACED IN :F1:SCANIN. OBJ 
COMPILER INVOKED BY: PLM88 : Fl : SCANIN. PLM DEBUG 



ITITLE( 'SCANIN: RMX/88 REAL-TIME CLCC: EXAMPLE') 
1 SCANIN: DO; 

* THIS TYPED PROCEDURE SCANS A STRING OF NUMERIC ASCII CHARACTERS 

* AND RETURNS THE EQUIVALENT BINARY VALUE THE STRING CAN BE A 

* BINARY, OCTAL.. DECIMAL OR HEXADECIMAL REPRESENTATION OF A NUMBER 

* THE PARAMETER 'PTRIPTR' CONTAINS TH: ADDRESS OF THE BEGINNING 

* OF THE STRIHG. LEADING BLANKS ARE IGNORED. NOTE THAT SCANIN 

* ASSUMES THAT THE STRING IT IS SCANNING IS VALID, SURPRISING RESULTS 

* MAY BE OBTAINED IF IT ISN'T. 



2 1 SCANI INTEGER: PROCEDURE (PTRIPTR) ADDRESS PUBLIC; 

3 2 DECLARE PTRIPTR ADDRESS; 

4 2 DECLARE ORIGIPTR BASED PTRIPTR ADDRESS; 

5 2 DECLARE (SCANIPTR, UPDATEIPTR, STOPIPTR) ADDRESS; 

6 2 DECLARE CHAP EASED SCANIPTR BYTE; 

7 2 DECLARE a, RADIX, INCREMENT) BYTE; 

8 2 DECLARE (NVAL, OVAL) ADDRESS, 

9 2 DECLARE DIGITS 1 :*) BVTE DATA('01234<S789ABCDEF')i 

18 2 SCANIPTR = ORIGIPTR; 

11 2 DO WHILE CHAR = ' '; 

12 3 SCANIPTR = SCANIPTR + 1; 

13 3 END, 

14 2 ORIGIPTR = SCANIPTR; 

15 2 DO WHILE CCHAR > '9' AND' CHAR <= '9') OR 

(CHAR >= 'A' AND CHAR <= F'); 

16 3 SCANIPTR = SCANIPTR + 1; 

17 3 END; 

18 2 UPDATEIPTR = (STOFIPTP := SCANIPTR: + 1; 

19 2 IF CHAR = 'H' THEN DO, 

21 3 RADIX = 16; 

22 3 END; 

23 2 ELSE DO; 

24 3 IF CHAR = '0' OR CHAR = '0' THEI DO, 

26 4 RADIX = 8; 

27 4 END; 
23 3 ELSE DO; 

29 4 STOPIPTR, SCANIPTR = (UPDATE; PTR := SCANIPTR) - 1, 

38 4 IF CHAP = 'B' THEN DO, 

32 5 RADIX = 2 

33 5 END; 

34 4 ELSE DO; 

35 5 RADIX = 18, 

36 5 IF CHAR O 'D' THEN DO, 

38 6 STOPIPTR = STOPIPTR + :., 

39 6 END; 

40 5 END, 

41 4 END; 

42 3 END, 
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PL/M-80 COMPILER SCANIN: RMX/88 REAL-TIME CLOCK EXHMPLE 



fEJECT 



43 


2 


SCANtPTR = ORIfilPTP- 


44 


2 


NVfiL, OVAL = 8; 


45 


2 


DO WHILE SCANtPTR <" STQPiPTR; 


46 


3 


DO I - 8 TO LAST(DIGITS); 


47 


4 


IF CHAR = DIGITS(I) THEN INC-REMENT 


49 


4 


END; 


56 


3 


IF INCREMENT >= RADIX THEN RETJRN 8, 


52 


3 


NVflL * OVAL * RADIX + INCREMENT 


53 


3 


IF NVHL < OVAL THEN RETURN ft 


55 


3 


OVAL = NVfiL; 


56 


3 


SCAN$PTR = SCfltBPTR + is 


57 


3 


END; 


58 


9 

c 


ORIGtPTR = UPDATEIPTR; 


59 


2 


RETURN NVflL; 


69 


2 


END SCAN! INTEGER; 


61 


1 


END; 



MODULE INFORMATION: 

C0C€ AREA SIZE = 817AH 378D 
VARIABLE AREA SIZE = 688FH 15D 
MAXIMUM STACK SIZE = 8884H 4D 
67 LINES READ 
PROGRAM ERRORCS) 

END OF PL/M-ee COMPILATION 
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PL/M-88 COMPILER ONESEC: RMX/88 REAL-TIME CLOCK EfflHPLE 



PAGE 1 



ISIS-1I PL/M-88 V3. i COMPILATION OF MODULE ONESEC 
OBJECT MODULE PLACED IN :Fi: ONESEC. OBJ 
COMPILER INVOKED BY: PLM88 :Fi: ONESEC. PLM DEBUG 



$TITLE( 'ONESEC: RMX/88 REAL-TIME CLOCK EXAMPLE') 



1 



ONESEC: DO; 

* PRIORITY 

* RECEIVES 




138 

MESSAGE— 
TIME$OUT$TYPE 



-FROM— 
RMX/88 



-VIA- 
WAITX 



COMMENTS 

1 SECOND TIME OUT 



SENDS: 



MESSAGE- 



T0- 



-VIA- 



COMMENTS 



ADVANCEtTIME UPTIME UPTIMX ADVANCE CLOCK 1 SECOND 

USES PUBLIC PROCS: RQHAIL R6SEND< PJCXCH 
READS PUBLIC DATA: NONE 
WRITES PUBLIC DATA: NONE 

FUNCTION: THIS IS THE HIGHEST PRIORITY TASK IN THE SYSTEM, IT 
SIMPLY WAITS FOR ONE SECOND AND TIEN INFORMS UPTIME THAT 
ONE SECOND HAS PASSED' 

NOTE THAT IN ORDER TO MAINTAIN SYICHRONIZATI0N HITH THE 
HARDWARE CLOCK, ONESEC MUST DO IT> THING AND GET BACK ON 
THE WAIT LIST (ISSUE AN RQHAIT) BiFORE THE NEXT "TICK" OF 
THE CLOCK <5e MS). 
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PL/M-88 COMPILER ONESEC: RMX/88 RERL-TIME CLOX EXAMPLE 



*EJECT 

♦INCLUDE <:Fi:EXCH. ELT) 

2 1 = DECLARE EXCHANGE*DESCRIPTOR LITERRL.V 'STRUCTURE ( 

= HESSAGE$KEAD ADDRESS, 
= MESSAGEfTAIL ADDRESS, 
= TASK$HEAD ADDRESS, 
= TASWAIL ADDRESS, 
= EXCHANGEtLINK ADDRESS)'; 
♦INCLUDE (:F1:MSQ. ELT) 

3 1 = DECLARE MSttHDR LITERALLV ' 

= LINK ADDRESS, 

= LENGTH ADDRESS, 

= TYPE BYTE, 

= HONESEXCHANGE ADDRESS, 

= RESPONSEtEXCHANGE ADDRESS'; 

4 1 = DECLARE MSG$DESCRIPTOR LITERALLY 'STRUCTUREC 

= HSG$HDR, 

= REMAINDER(l) BYTE)'; 

/♦MISCELLANEOUS VARIABLES*/ 

5 1 DECLARE HAIT$PTR ADDRESS; 

6 1 DECLARE FOREVER LITERALLY 'HHILE t'i 

/♦MESSAGES*/ 

7 1 DECLARE ADVANCE$TIME STRUCTURE( 

MSGIHDR) PUBLIC; 

/♦EXCHANGES*/ 

8 1 DECLARE WAITX EXCHANGE$DESCR I PTOR; 

9 1 DECLARE UPTIMX EXCHANC€$DESCRIPTOR PUBLIC; 

/♦EXTERNAL PROCEDURES*/ 

18 1 RQCXCH: PROCEDURE(EXCHANGE$PTR) EXTERNAL, 

11 2 DECLARE EXCHANGEJPTR ADDRESS; 

12 2 END RQCXCH; 

13 1 RQSEND: PROCEDURE (EXCHANGEtPTR, ME5SAGEJPTR) EXTERNAL; 

14 2 DECLARE (EXCHANGEIPTR, MESSAGE$P1R) ADDRESS; 

15 2 END RQSEND; 

16 1 RQWflIT: PROCEDURE(EXCHANGE$PTR, DELAY) ADDRESS EXTERNAL; 

17 2 DECLARE CEXCHANGEIPTR, DELAY) ADCRESS, 

18 2 END RQHAIT; 
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PL/H-88 COMPILER ONESEC: RMX/80 REAL-TIME CLOCK EXAMPLE 



PAGE 2 



19 
20 
21 

22 
23 



24 
25 
26 
27 
28 
29 



$EJECT 

/♦INITIALIZATION*/ 
ONESEC: PROCEDURE PUBLIC; 

CALL RQCXQK. HAITX); 

CALL RQCXCHC. UPTIMX); 

ADVftNCE$TIME. LENGTH = SIZE(ADVANCE$1IME); 

ADVANCED I ME. TVPE = 100; 

/*MAIN PROCESSING LOOP*/ 
DO FOREVER; 

HAITWTR = RQHAITC HAITX, 20); /*0NE SECOND*/ 

CALL RQSENDC. UPTIMX, . ADVANCEtTIMD, /*TELL UPTIME TO BUMP CLOCK*/ 
END; 
END ONESEC; 
END; 



MODULE INFORMATION: 

CODE AREA SIZE = 0039H 
VARIABLE AREA SIZE = 981FH 
MAXIMUM STACK SIZE = 8082H 
84 LINES READ 
PROGRAM ERROR(S) 

END OF PL'tl-80 COMPILATION 



48D 
31D 
2D 
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PL/M-88 COMPILER CONSOL: RMX/SO REAL-TIME CLOCK EXAMPLE 



ISIS-II PL/M-SO VI 1 COMPILATION OF MODULE CONSOL 
OBJECT MODULE PLACED IN :F1: CONSOL OBJ 
COMPILER INVOKED BY: PLM88 :Fi: CONSOL. PLM DEBUG 



RW80 REAL-TIME CLOCK EXAMPLE') 



$T1TLEC CONSOL. 
CONSOL: DO; 

* PRIORI TV: ISO 

MESSAGE FROM 

COMAHD T. H. 
REPLV T. H. 



-VIA — 

CREADX 

CWRITX 



COMMENTS 

T.H. RESPONSE 
T. H RESPONSE 



COMAND T. H. 
REPLV T. H. 

SET$TIME UPTIME 

ENABLEfDISPLAV UPTIME 



-VIA 

RQINPX 

mam 

UPTIMX 
UPTIMX 



REQUEST INPUT 
RESPONSE TO COMMAND 
SET REAL/ALARM TIME 
START/STOP TIME DISPLAV 



RfiSENC i RSCXCH, SCAN$INTEGER 



* RECEIVES 

* . 
* 

* SENDS: MESSAGE TO 

* 
* 
* 
* 

* USES PUBLIC PROCS: 6M£t 

* READS PUBLIC DATA: NONE 

* WRITES PML1C DATA: NONE 
* 

* FUNCTION: THIS TASK COORDINATES INTERACTION WITH THE -USER AT THE 

* TERMINAL. IT 

* L SIGNS ON WHEN THE SVSTEM COMES UP. 

* 2. ACCEPTS COMMANDS. 

* 3. EXECUTES VALID COMMANDS, WRITES AN ERROR MESSAGE 

* TO THE DISPLAV IF IT RECEIVES AN INVALID COMMAND. 

* 4. DISABLES THE AUTOMATIC TIME DISPLAV DURING DATA ENTRV. 

* VALID COMMANDS ARE. 

* C (SET REAL-TIME CLOCK") 

* A (SET ALARM) 

* ? (DISPLAV COMMAND MENU) 

* Cfl "NULL" COMMAND -CR OHLS- STOPS THE TIME DISPLAV 

* WHEN T OR fi IS ENTERED/ CONSOL PROMPTS FOR THE TIME (HH:MM:SS?). 



PL'M-80 COMPILER CONSOL. RHX/88 REAL-TIME CLOCK EXAMPLE 



IEJECT 

INCLUDE (FLEXCH.ELT) 

2 1= DECLARE EXCHANGE$DE5CR I PTOR LITERALLV 'STRUCTURE ( 

« MESSAGE$HEAD ADDRESS, 
- MESSAGE*TAIL ADDRESS, 
= TflSKtHEAD ADDRESS, 
= TASKJTAIL ADDRESS, 
= EXCHANGE$LINK ADDRESS)'; 
IINCLUDE (:F1:MSG. ELT) 

3 1 = DECLARE MSG$HDR LITERALLV ' 

= LINK ADDRESS, 

= LENGTH ADDRESS, 

= TVPE BVTE, 

= HOME$EXCHANGE ADDRESS, 

« RESPONSE$EXCHANG£ ADDRESS'; 

4 1= DECLARE MSGJDESCRIPTOR LITERALLV 'STRJCTURE( 

= HSGJHDR, 

= REMAINDER(l) BVTE)'; 
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System Example: A Real Time Clock 



PAGE 3 



*EJECT 

/♦EXCHANGES*/ 

5 1 DECLARE (RGOUTX, 

RQINPX, 

UPTIMX) EXCHHMGEIDESCRIPTOR EXTERNAL; 

6 1 DECLARE CCREADX.. CWRITX) EXCHANGEJDESCR IPTOR; 



/♦MISCELLANEOUS VARIABLES*/ 

7 1 DECLARE FOREVER LITERALLY WHILE i'i 

8 1 DECLARE HAIT$PTR ADDRESS; 

9 1 DECLARE MRITRTYPE LITERALLV '12'; 
18 i DECLARE REFMTVPE LITERALLV '8'; 

11 1 DECLARE READIPTR ADDRESS; 

12 1 DECLARE CR LITERALLV "8DH'< /CARRIAGE RETURN*/ 

13 1 DECLARE LF LITERALLV '8AH ; /*LINE FEED*/ 

14 1 DECLARE EXPECTING$TIME BYTE; /*NEXT C( MMflND SHOULD BE TIME*/ 

15 1 DECLARE TRUE LITERALLV 'OFF!-/; 

16 1 DECLARE FALSE LITERALLV 'M8T; 
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PL/H-39 COMPILER COHSOL: RMX/88 REfiL-TlME CLOCK 



PAGE 4 



(EJECT 



1? 1 



/♦MESSAGES*/ 

DECLARE (REPLY, COMAND) STRUCTURE ( 



MSG*HDR, 

STATUS ADDRESS, 

BUFFERfADP ADDRESS, 

COUHT ADDRESS, 

ACTUAL ADDRESS), 



19 i 



18 1 



DECLARE ENABLEtDISFLRV STRUCTURt ( 

BSGtHDR) EXTERNAL, 
DECLARE SETtTIME STRUCTURI ( 



MSGfHDR, 

NEWtHR BYTE, 

NEW$NIN PATE, 

HEUJSEC EVTE) EXTEI:NAL, 



29 1 DECLARE SIGMOWMSGv*) PVTE DATA( 

CR, LF, 'RTCLOK: VERSION 1. 6', CR, LF, LF, 

'ALL TIMES ARE 24-HOUR l : ORHRT: HH:MH:SS',CR,LF, 

69:22:30 = 9.22:38 AM', CR, LF, 

17:38:00 = 5:38 PH',CR,LF, 

88:88:80 = MIDNIGHT'/ CR, LF, 
' 24:88:88 = NO TIME - CLOCK IS OFF", CR, LF); 

21 1 DECLARE MENUWSG(t) PVTE DATA* 

CR, LF, 

'AVAILAPLE COMMANDS: ',C?,LF, 

' C = SET REAL-TIME 10CK ,Cfi,LF , 

' A = SET ALARM ' . CR, S, 

' ■> = DISPLAV THIS C 5MMAND HENU',CR,LF, 

'ENTERING A "NULL COMMA©" (CARRIAGE RETURN 0NLV)',CR,LF, 

'SUSPENDS THE AUTOMATIC TIME DISPLAV. ',CR,LF, 

'IF VOU ENTER C OR A, T€ SVSTEM WILL PROMPT YOU TO', 

CR,LF, 'ENTER A TIME. '. 

'REMEMBER TO PUT IN COL DNS. ',CR, LF, LF, 

'TO SHUT OFF THE ALARM, SET IT TO 24:88:88. ',CR,LF); 

22 1 DECLARE TIME*MSG(*) BYTE DATA( 

CR.LF, 'HH:MM:SS?',CR,LF); 

23 1 DECLARE INVAL!DtHSG<*) PATE DATA( 

CR, LF, ' INVALID COMMAND' , CR, LF); 

24 1 DECLARE BflWTIHEWSG <*) EVTE OfiTflt 

CR,LF, 'TIME IS INVALID'. CR,LF), 

25 1 DECLARE C0MAND$NSG(88) EVTE; 
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(EJECT 

/♦EXTERNAL PROCEDURES*/ 

26 1 ROSEHD PPOCEDURE(EXCHflNGE$PTR» MES< AGEfPTR) EXTERNAL, 

27 2 DECLARE (EXCHfiNGEtPTR, MESSAGE JPTF ) ADDRESS, 

28 2 END PQSENO; 

29 1 RQHRIT: PROCEDUR£(EXCHRNGEtPTP, DELf V> ADDRESS EXTERNAL, 
38 2 DECLARE (EXCHfiMQEtRTR, DELAY) ADDRESS; 

31 2 END RONAIT, 

32 1 SJCXCH: PROCEDURE (EXCHANGEtPTR) EXTERNAL, 

33 2 DECLARE EXCHANGEIPTP ADDRESS; 

34 2 END RQDtCHi 

35 1 SCAN* INTEGER- PROCEDURE (PTR) ADDRESS EXTERNAL: 

36 2 DECLARE PTR ADDRESS; 

37 2 END SCRNtlNTEGER; 
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PL/M-88 COMPILER CONSOL: RMX/88 REAL-TIME CLOCK E SAMPLE PAGE 6 

IEJECT 

/♦INTERNAL PROCEDURES*/ 



38 


1 


TIt£*0N: PROCEDURE; 








/•♦TURN ON HUTO TIME DISPLAY*/ 




33 


2 


ENABLESDISPLAV. LENGTH = S I2E ( ENABLE! ) I SPLfl'V ) ; 




48 


2 


EHABLEJDISPLAY. TV'PE = 149; /*ENfiBL E*/ 




41 


2 


CALL RQSEMX. UPTIMX, . ENABLE f-DISPLRY) ; 




42 


2 


END TIMEION; 




43 


1 


TIHEIOFF: PP03ECHPE; 








/♦SHUT OFF AUTO TIME DISPLAY*/ 




44 


2 


ENABLEfDISPLAY. LENGTH = SIZE<ENAELEJ DISPLAY); 




45 


2 


ENABLEtDISPLRY. TYPE = 130; /*D!SABLE*/ 




46 


2 


CALL RQSENDC. UPTIMX, . ENABLEtDISPLAt); 




47 


2 


END TIME$OFF; 




48 


1 


ASKJFORITIME: PROCEDURE.; 








/♦DISPLAY "HH:MM SS?"*/ 




49 


2 


REPLY. BUFFERJADR = . TIME*MSG, 




50 


2 


REPLY. COUNT = SIZE(TIMEJMSG); 




51 


2 


CALL R8SEND(. RGOUTX, . REPLY); 




52 


2 


HfllTIPTP = R8HRITC CHRITX, 0); /W. T FOR T.K 


TO FINISH*/ 


53 


2 


E!<PECTING*TIHE = TRUE; /*HEXT COMMtlND SHOULD BE TIME SETTING*/ 


54 


2 


END ASl'*FOP*TIME; 




55 


1 


INVALID: PPOCEDi.iRE ; 








/♦DISPLAY ERROR MESSAGE*/ 




56 


2 


CALL TIMEIOFF; /*SHUT i3FF AUTO TIME DISPLAY*/ 




57 


2 


REPLY. BUFFERIADR = . INVALIDSMSG; 




58 


c 


REPLY. COUNT = SI2E(INVALID$MSG), 




59 


*> 
c 


CALL ROSENDC. ROOUTX, . REPLY); 




60 




HAITtPTP = RCWITf. CHRITX, 8); /*HA[T FOR T. H. 


TO FINISH*/ 


61 


2 


CALL TIMEtON, /*TURN AiJTO TIME DISPLAY BACK ON*/ 


62 


*> 

c 


END INVALID; 




63 


1 


BADSTINE: PROCEDURE; 








/♦REJECT INVALID TIME SETTING*/ 




64 


2 


CALL TIMEtOFF; A SHUT OFF AUTO TIM: DISPLAY*/ 




65 


2 


REPLY. BUFFEPtRDR = . BRDITIMEIMSG, 




66 


2 


PEFLY. COWT = S I ZE < BADJT I MEJMSG ) .■ 




67 


2 


CALL ROSENDi. ROOUTX, . REPLY); 




63 


2 


MAITJPTR = R6HWK. CHRITX.. O); /*HAIT FOR T. H. 


TO FINISH*/ 


69 


2 


CALL TIMEWN; PRESUME AUTO TIME DISPLAYS 




79 


2 


END BAD$TIME; 
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PL/M-88 COMPILER CONSOL: RMX/88 REAL-TIME CLOO EXAMPLE 



$EJECT 

71 1 SET$REAL: PROCEDURE; 

/*SET REAL-TIME CLOCK*/ 

72 2 CALL TIMEIOFF; /*TURN OFF AUTO TIME DISPLAY*/ 

73 2 SETtTIME. LENGTH = SIZE<SET$TIME); 

74 2 SETtTIME. TVPE = 128; /*SET REAL-TIME CLOCK*/ 

75 2 CALL ASK$FOR$TIME, /*GET THE TIME VALUE TO SET*/ 

76 2 END SETtREAL; 

77 1 SET$ALARM. PROCEDURE; 

/*SET ALARM*/ 

78 2 CALL TIMEJOFF; ATURN OFF AUTO TIME DISPLAY*/ 

79 2 SETtTIME. LENGTH = SIZE(SETITIME), 

88 2 SETtTIME. TVPE * 118; /+SET ALASM CLOCK*/ 

81 2 CALL ASK'tFORtTIME; /*GET THE TIME VALUE TO SET*/ 

82 2 END SETtALARM; 

83 1 MENU: PROCEDURE; 

/♦DISPLAY VALID COMMANDS*/ 

84 2 CALL TIHEtOFF; /*SHUT OFF AUTO TIME DISPLAY*/ 

85 2 REPLY BUFFERtADR = . NENUtMSG; 

86 2 REPLY. COUNT = SIZE(HENUtMSG); 

87 2 CALL Rt!SEND(. R0OUTK- . REPLY); 

88 2 WAITtPTR = RQWAITC CHRITX.. 8); /*tAIT FOR T. H. TO FINISH*/ 

89 2 CALL TIMEtON, /*RESUME AUTO TIME DISPLAY*/ 
98 2 END MENU; 

91 1 SUPPLVtTIME: PROCEDURE; 

/*PASS THE TIME SETTING TO UPTIME*/ 

92 2 DECLARE PTR ADDRESS; 

93 2 PTR = COMfiND BUFFERtADR; 

94 2 SETtTIME. NEWtHR = SCANtlNTEGERC PTR); /+ASCII TO BINARY*/ 

95 2 PTR = PTR + 1; /*G0 PAST COLON* -' 

96 2 SETtTIME. NEWtMIN = SCAN* INTEGERS PTR); 

97 2 PTR = PTR + 1; AGO PAST COLON* ' 

98 2 SETtTIME. NEWtSEC = SCANtlNTEGERC PTR); 

/♦VALIDATE THE SETTING*/ 

99 2 IF (SETtTIME. NEHtHR < 24 AND 

SETtTIME. NEWtMIN < 68 AND 
SET$TIME. NEWtSEC C 68) 
OR 

(SETtTIME NEWtHR * 24 AND' 
SETtTIME. NEHtHIN = 8 AND 
SETtTIME. NEWtSEC = 8) 
THEN CALL RQSEND(. UFTIMX, . SETtTIME); 

181 2 ELSE CALL BAD$TIME; /DISPLAY ERRDR MESSAGE*/ 

182 2 CALL TIMEtON, /*RESUME AUTO TIME )ISPLAV*/ 

183 2 EXPECT I HOST I ME = FALSE; /*HEXT CO WAND SHOULD BE H,T, ?*/ 

184 2 END SUPFLY$TIME; 

185 1 REJECTtCOHMAND: PROCEDURE; 

/♦THROW OUT AN INVALID COMMAND 1 */ 

186 2 CALL INVALID; /*DISPLAY ERROR MESJAGE*/ 

187 2 CALL MENU; /*DISPLAY VALID COMMAND*/ 

188 2 END REJECT$COMMAND; 
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*EJECT 

/♦INITIALIZATION*/ 1 

199 1 CONSOL: PROCEDURE PUBLIC. 

118 2 CALL RQCXCHC. CWRITX); /*HHERE HE HUT FOR T. H OUTPUT TO COMPLETE*/ 

111 2 REPLV. LENGTH = SIZECREPLY); 

112 2 REPLV. TYPE = HRITEtTYPE; 

113 2 REPLV RESPONSE$EXCHANGE = . CHRITX; 

114 2 REPLV. BUFFER$ADR = . SIGNONtMSG; 

115 2 REPLV. COUNT = SIZECSIGHON$MSG), 

116 2 CALL RQSEWK. R90UTX,. REPLV); /*DISPLAY SIGNON MESSAGE*/ 

117 2 HAITIPTR = RQHAIT(.CHRITX,8); 

118 2 CALL MENU, /*OISPLAV VALID COMMANCS*/ 

119 2 CALL RQCXCHC CREADX); /*WHERE WE hfilT FOR T. H. INPUT*/ 

120 2 COMAND. LENGTH = SIZE'COMAND); 

121 2 COMAND. TVPE = REAOITVPE; 

122 2 COMAND RESPONSEfEXCHANGE = . CREADX, 

123 2 COMAND. BUFFER$ADR = . COMANDtMSG; 

124 2 COMAND. COUNT = SIZE(COMANDtMSG); 

125 2 EXPECTING$TIME = FALSE; 

/♦MAIN PROCESSING LOOP*/ 

126 2 DO FOREVER; 

/♦REQUEST A COMMAND FROM THE TERNIfAL HANDLER*/ 
12? 3 CALL RSSENDt RQINPX, . COMAND); 

128 3 READtPTR = R8HAIT(. CREADX, 8>i /*Hf IT FOR T. H TO FINISH*/ 

/♦CALL A PROCEDURE TO PROCESS THE COMMAND*/ 

129 3 IF COMAND$MSG<8) = 

THEN CALL SET$REAL, /*SET THE (LOCK*/ 
131 3 ELSE IF COHAND$MSG<e> = 'A' 

THEM CALL SETtALARM; /*SET THE ALARM*/ 
133 3 aSE IF COMANDtMSGCO) = '?' 

THEN CALL MENU; /*DISPLAV VALID COMMANDS*/ 
135 3 ELSE IF C0MAHDtMSG(8) = CR /*CARF:: AGE RETURN ONLY*/ 

THEN CALL TIMEIOFF; /*SHIJT OFF AUTO TIME DISPLAY*/ 
137 3 ELSE IF EXPECTINGtTIME 

THEN CALL 9JPPLWIME; /*GET CI.OCK/ALARM SETTING VALUE*/ 
139 3 ELSE CALL REJECTtCOMMAND; /*REJEC" THE INVALID COMMAND*/ 

148 3 END; 

141 2 END CONSOL; 

142 1 END; 



MODULE INFORMATION: 

CODE AREA SIZE = 847CH 1148D 
VARIABLE AREA SIZE = 888DH 141D 
MAXIMUM STACK SIZE = 88eSH 8D 
266 LINES READ 
8 PROGRAM ERROR(S) 

END OF PL/M-88 COMPILATION 
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PL/Tf-88 COHPILER UPTIME: mm REAL-TIME CL0C< EXAMPLE PAGE 1 



ISIS-II PL/M-88 V3.1 COMPILATION OF MODULE UPTIME 
OBJECT MODULE PLACED IN :F1: UPTIME. OBJ 
COMPILER INVOKED BV: PLM88 : Fi: UPTIME. PLM DEBUG 



ITITLE( 'UPTIME: mm REAL-TIME CLXK EXAMPLE') 
i UPTIME: DOi 

* PRIORITV: 168 



* RECEIVES: MESSAGE FR01 VIA COMMENTS 

* ADVANCEtTIME OHESEC UPTIMX ADVANCE CLOCK 1 SECOND 

* SETtTIME C0NS)L UPTIMX SET REAL OR ALARM 

* ENA6LE$DISPLAV CONSDL UPTIMX AUTO TIME ONAFF 

* SHOWTIME TERMHWLR UMRITX T. H. RESPONSE 
* 

* SENDS: MESSAGE TO VIA COMMENTS 

* SHOWTIME TERM. H«LR RSOUTX AUTO TIME DISPLAY 
* 



* USES PUBLIC PROCS : ROWAIT, RQSEND , RQCXCH, NUMOUT 

* READS PUBLIC DATA: REfUTIHE,ALA*M*TIME 

* WRITES PUBLIC DATA: REALtTIME, ALflWTIME 
* 

* FUNCTION: THIS TASK IS IN CHARGE OF MAINTAINING THE REAL-TIME 

* CLOCK AND THE ALARM. THIS INCUDES: 

* 1 SET REAL-TIME CLOCK. 

* 2. SET ALARM. 

» 3. ADVANCE REAL-TIME CLOCK 1 SECOND (IF IT IS RUNNING). 

* 4. DISPLAY THE VALUES OF REA.-TIME CLOCK AND ALARM 

* (IF DISPLAY IS ENABLED). 

* 5. IF REAL-TIME >= ALARM SETTING, ADD ALARM INDICATION 

* TO THE TIME DISPLAY. 
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PL/M-88 COMPILER UPTIME: RMX/80 REAL-TIME CLOCK EXAMPLE PAGE 2 

*EJECT 

^INCLUDE <:F1:EXCH.ELT) 

2 1 = DECLARE EXCHANGE$DESCRIPTOR LITERALLV STRUCTURE ( 

MESSAGEIHEAD ADDRESS, 
= MESSAQE$TAIL ADDRESS, 

TASKtHEAD ACCESS, 
= TASK*TAIL ADDRESS, 
= EXCHANGE$LINK ADDRESS)'; 
♦INCLUDE < :F1:MSG.ELT) 

3 1= DECLARE MSGWDR LITERALLV ' 

« LINK ADDRESS, 
= LENGTH ADDRESS, 
= TVPE BVTE, 
= HOMEIEXCHANGE ADDRESS, 
= RESPONSE$EXCHANGE ADDRESS'; 



'STRUT 



4 1 = DECLARE MSGIDESCRIPTOR LITERALLV 'STRUC HREC 

= MSGIHDR, 

= REMAINDER(l) BVTE)'; 

/♦MISCELLANEOUS VARIABLES*/ 

5 1 DECLARE FOREVER LITERALLV 'WHILE 1'; 

6 1 DECLARE HRITE$TVPE LITERALLV '12*; 

7 1 DECLARE TRUE LITERALLV '8F-"H', 

8 1 DECLARE FALSE LITERALLV '86JH'; 

3 1 DECLARE ( D I SPLAVtENABLED, ALARM$ENABLED ) BVTE; 

16 1 DECLARE TH*RTN$MSG ADDRESS; 

11 1 DECLARE IN$MSGtADDR ADDRESS; 

12 1 DECLARE DECODEtMSG BASED IN$MSG*"IDDR STRUCTURE ( 

MSG*HDR); 

13 1 DECLARE FIRSTITIME BVTE; 

14 1 DECLARE CP LITERALLV 'BW; /*CARRIAGE RETURN*/ 

15 1 DECLARE LF LITERALLV Wi /*LIH£ FEED*/ 

/♦EXCHANGES*/ 

16 1 DECLARE (UPTIMX, RQOUTX) EXCHANGEIDESCR1PT0R EXTERNAL, 

17 1 DECLARE UHRITX EXCHAHGEJDESCRIPTOR; 

/♦INPUT MESSAGES*/ 

18 1 DECLARE ADVANCEJTIME STRUCTURE ( 

MSGWR) EXTERNAL; 

19 1 DECLARE ENABLEtDISPLAV STRUCTURE ( 

HSGIHDP) PUBLIC, 

20 1 DECLARE SETtTIHE STRUCTURE ( 

HSGSHDR, 

HEWtHR BVTE, 

NEH$MIN BVTE, 

NEW$SEC BVTE) PUBLIC; 

/♦PUBLIC TIME VARIABLES*/ 

21 1 DECLARE <REAL$TIME, ALARMJTIHE) STRUCTUft ( 

HR BVTE, 
MIN BVTE, 
SEC BVTE) PUBLIC; 
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PL/M-88 COMPILER UPTIME: RNJV86 REfiL-TINE CLOCK EXAMPLE PAGE 3 

$EJECT 

/♦EXTERNAL PROCEDURES*/ 



22 


1 


RQCXCH: PROCEC«E(EXCHANGE$PTR> EXTERNAL 


23 


2 


DECLARE EXCHANGEJPTR HC-DRESS; 


24 


2 


END RQCXCH; 


25 


1 


RQSEND: PROCEDURE(EXCHflNGE*PTP.,MES:;flGE$PTR) EXTERNAL, 


26 


2 


DECLARE (EXCHANGE*PTR,MESSAGEIPTI!) ADDRESS; 


27 


2 


END RQSEND; 


28 


1 


RQHAIT: PRCCEDURE<EXCHANGE*PTR,DELHV) ADDRESS EXTERNAL; 


29 


2 


DECLARE <EXCHANG£$PTR,DELAV> ADORESS; 


38 


2 


END RQWAIT; 


31 


1 


NUHOUT: PROCEDURECVflLUE, BASE, LC, BUI-"ADR. HIDTH) EXTERNAL; 


32 


2 


DECLARE (VALUE, BUFADR) ADDRESS; 


33 


2 


DECLARE (BASE, LC, WIDTH) BVTE; 


34 


2 


END NUMOUT; 
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PL/M-88 COMPILER UPTIME: RMX/88 REAL-TIME CLOCK EXAMPLE PAGE 4 



$EJECT 

/♦INTERNAL PROCEDURES*/ 



35 1 ADVANCE: PROCEDURE; 

/♦BUMP THE aOCK IF IT'S RUNNING*/ 

36 2 IF REAL$TIME. HR O 24 THEN DO; 

/♦CLOCK IS RUNNING, ADVANCE IT*/ 

38 3 REALITIME. SEC = REALITIME. SEC + :.; 

39 3 IF REALITIME. SEC = 68 THEN DO; 

41 4 REALITIME. SEC = 8; 

42 4 REALITIME. MIN = REAL-TIME. MIN + 1; 

43 4 IF REALITIME. MIN = 68 THEN DO, 

45 5 REALITIME. MIN = 8; 

46 5 REALITIME. HR = REAL$TIME. HR + 1; 
4? 5 IF REALITIME. HR = 24 THEN I'O; 

/♦ROLL TO NEXT DAW 

49 6 REALITIME. HR = 8; 

58 6 REALITIME. MIN = 8; 

51 6 REALITIME. SEC = 8; 

52 6 END, 

53 5 END; 

54 4 END; 

55 3 END; 

56 2 END ADVANCE; 

57 1 SET: PROCEDURE, 

/♦SET THE CLOCK OR ALARM ACCORDING TO MSG TYPE*/ 

58 2 IF SETITIHE. TYPE = 128 THEN DO; 

68 3 REALITIME. HR = SETITIHE. NEMIHRj 

61 3 REALITIME. MIN = SETITIME. NEHIMIN; 

62 3 REALITIME SEC = SETITIME NEHISEC 

63 3 END; 

64 2 ELSE IF SETITIME. TYPE - 118 THEN DO; 

66 3 ALARMITIME. HR = SETITIME. NEHIHR, 

67 3 ALARMITIME MIN = SETITIME. NEWIMIN; 

68 3 ALARMITIME. SEC = SETITIME NEHISEC; 

69 3 IF ALARMITIME. HR = 24 THEN /*24 MEANS ALARM IS NOT SET*/ 
78 3 ALARMIENABLED = FALSE; 

71 3 ELSE ALARMIENABLED = TRUE; 

72 3 END; 

END SET; 



74 1 ENABIDISPLAY: PROCEDURE; 

/♦TURN AUTO TIME DISPLAY ON/OFF*/ 

75 2 IF ENABLEIDISPLAV. TVPE = 148 THEN 

76 2 DISPLAVIENABLED = TRUE; 

77 2 ELSE IF ENABLEIDISPLAV. TYPE = 138 THEN 

78 2 DISPLAYIENABLED = FALSE; 

END ENABIDISPLAY; 
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88 1 

81 2 



82 2 



83 
84 
85 



$EJECT 

SHOW: PROCEDURE; 

/♦DISPLAY SETTINGS OF CLOCK AND ALARM*/ 
DECLARE SHOWTIME STRUCTURE^ 
MSGIHDR, 

STATUS ADDRESS; 

BUFFERtADR ADDRESS, 

COUNT ADDRESS, 

ACTUAL ADDRESS); 
DECLARE TIMEIMSG STRUCTURE( 
T1MEJLABLC9) BYTE, 
TIHRC2) BYTE, 
COL0N1 BVTE, 
T$MIN(2) BYTE, 
COLONS BVTE.. 
T*SECC2> BVTE, 
ALARMILABL'.S) BVTE, 
AIHR(2) BVTE, 
C0LGN3 BVTE, 
A*MIN<2> BVTE, 
C0L0N4 BVTE, 

mm® bvte, 

CARRIAGE BVTE, 

mmmm> mo 

DECLARE BELL LITERALLY '97H , 
DECLARE ALARM$IHDICATION(5/ BVTE DATA' ' ! ', BELL, 
DECLARE T1HE$C0NST(9) BVTE DATA ' ' TIME= ' >; 
DECLARE ALARM$CONST(8j BVTE DATlif '--ALARM- ' >; 



',BELL, CR); 



8? 2 



89 



91 3 

92 3 



93 
94 
95 
% 
97 



IF FIRSTJTIME THEN DO; 

/♦INITIALIZE MESSAGE TEXT*/ 

CALL MOVE(SIZE<TIME*MSG. TIMEiABL), . TIMEfCONST, . TIMEJMSG. TIMEtLABL); 
TIMEIMSG. COLONl, TIHEJHSG. COLONS, 
TIMEJMSG. C0LON3, TIMEtHSG C01.0N4 s '":'; 

CALL MOVECSIZEaiMEfKSG. ALARWLAEL), . ALARI'WCONST, . TIMEIMSG. ALARMtLABL), 
CALL PtOVE<SIZE(TIME*NSG. ALAR! ItMSGX. 

. RLffiiW INDICATION, . TIMEtHSG. ALARMtHSG), 
/♦INITIALIZE MESSAGE FIELDS*.' 
SHOWTIME LENGTH = SIZECSHOWTIME); 
SHOWTIME. TVPE = HPITEtTVPE, 
SHOWTIME. RESPONSEJEXCHANGE ~ Mm 
SHOWTIME. BUFFER'tADP = TIME- 'MSG, 
END, 
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IEJECT 

/♦WAIT FOR T.H. TO OUTPUT PREVIOUS M -SSftGE*/ 
38 2 IF HOT FIRST$TIME 

THEN TH*RTN*MSG » RQHAITC. UWRITX, 3); 

/♦CONVERT TIME * ALARM TO ASCII*/ 

186 2 CALL NUMGUT(REAL$TIME HR.. 18, '8', . TIMEfMSG. TIHR, 2); 

181 2 CALL NUMOUT''REAL$TIME. MIN. 18.. '8', TIlEtMSG. TIMIN, 2); 

182 2 CALL NUMOUT(REAL$TIME. SEC 18, '8'. . TIlEtMSG. T$SEC, 2); 

183 2 CALL NUMQfJT ( ALARMIT I ME. HR, 18, '8', . TIPOMSG A$HR, 2), 

184 2 CALL NUMOUT(ALARM$TIME. MIN, 18, '8', . T IMEtMSG. AtMIN, 2), 

185 2 CALL NUMOUT<ALARM$TINE. SEC, 18, ' 8 ', . 1 IMEt-MSG. AISEC, 2), 

/♦CHECK FOR ALARM INDICATION*/ 

/♦ASSUME NO ALARM - SET COUNT TO EXCLUDE ALARM INDICATION*/ 

186 2 SHOWTIME. COUNT = SIZE(TIMEtMSG) - 

SIZEaiMEtMSG. ALAf MJMSG), 

187 2 TIMEIMSG. CARRIAGE = CP, 

188 2 IF ALAPH$ENftBLED 

THEN IF REALtTIME. HR O 24 /*24 : CLOCK NOT RUNNING*/ 
THEN IF (PEALfTIIC HR = ALARM* TIME. HP AND 
REfiLITIME. MIN = ALARiflTIHE. MIN AND 
REALf-TIME. SEC >= ALA!:M$TIHE. SEC) 
OR (PEALJTIME. HR = ALARM: TIME. HR AND 
REALJTIME. MIN > ALAR!!*TIME. MIN) 
OR (REALiTIME. HR > ALARM: TIME. HR) 
THEN DO; /*BUMP COLINT JO INCLUDE ALARM INDICATION/ 

112 3 SHOWTIME. COUNT = SIZlj'TIMEJHSG), 

113 3 TIMEfMSG. CARRIAGE = ' 'i /*ZAP 1ST CP IN MSG*/ 

114 3 END; 

/♦SEND THE MESSAGE TO THE TERMINAL HANDLER*/ 

115 2 CALL RSSENDC RQOUTX, . SHOH$TIME\: 

116 2 FIRSTJTIME = FALSE; 

117 2 END SHOW; 
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$EJECT 

118 1 UPTIME: PROCEDURE PUBLIC, 

/♦INITIALIZATION*/ 

119 2 CALL RQCXOK. UWRITX), /*HHERE HE WAIT FOR T. H. TO COMPLETE*/ 

128 2 REALfTIME.HR,ALHRHtTINE HR = 24; 

121 2 REFUTIME MIN, REALCTIME SEC = 6; 

122 2 ALARMtTIME. MIN, ALARH$TIME. SEC = 8 

123 2 DISPLAY$ENABLED, ALARN$ENABLED = RISE; 

124 2 FIRSWIME = TRUE; 

/♦MAIN PROCESSING LOOP*/ 

125 2 00 FOREVER; 

/♦GET THE NEXT MESSAGE IF THE?E IS ONE, OTHERWISE WAIT*/ 

126 3 IN*MS6$ADDR = ROMAITC. UPTIMX,8>; 

/CALL A ROUTINE TO PROCESS TH: MESSAGE*/ 

127 2 IF DECODE$MSG TVPE = 188 

THEN CALL ADVANCE; /*8UMP THE CLOCK 1 SECOND*/ 

129 3 ELSE IF ( DECODE WtSG. TVPE = 118 OP 

DECODEJMSG. TVPE = 128) 
THEN CALL SET; /*SET THE COCK OR THE ALARM*/ 
131 3 aSE IF (DECDDE$MSG. TYPE = 138 OR 

DECODE tMSG. TVPE ■ 148) 
THEN CALL ENABfDISPLAV; /*TURN THE AUTO TIME DISPLAY ON/OFF*/ 

/CHECK FOR TIME DISPLAY AND FLRRM*/ 
IF DISPLAV*ENABLED 

THEN IF DECODE tMSG. TYPE = 388 

THEN CALL SHOW; /*D I SPLAY TINE & ALARM SETTINGS*/ 

136 3 END; 

137 2 END UPTIME; 

138 1 END; 



MODULE INFORMATION: 

CODE AREA SI2E = 82DAH 738D 
VARIABLE AREA SIZE = 8864H 188D 
MAXIMUM STACK SIZE = 886AH 18D 
258 LINES READ 
8 PROGRAM ERROR(S) 

END OF PL/M-88 COMPILATION 
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ISIS-II PL/H-88 V3.1 COMPILATION of module nuhout 
OBJECT MODULE PLACED IN :F1: NUHOUT. OBJ 
COMPILER INVOKED BV: PLM88 Fl: NUMOUT. PLM DEBUG 



* 


VALUE: 


* 


BASE: 


* 


LC: 


* 




* 




* 


BUFADR 


* 




* 


WIDTH: 



$TITLE( 'NUMOUT: RMX/88 REAL-TIME CLOCK EXAMPLES 
HUHOUT. DO; 

* THIS PROCEDURE CONVERTS A BINARV VfUJE (BYTE OR ADDRESS) TO AN 

* ASCI! CHARACTER STRING THAT REPRESENTS THE VALUE OF THE NUMBER 

* IN A SPECIFIED BASE 

* PARAMETERS: 

THE BINARV NUMBER TO Bf CONVERTED 
BASE 'VALUE' IS TO BE REPRESENTED IN (2,8,18,16) 
LEFT FILL CHARACTER TO BE SUPPLIED IF THE LENGTH 
OF THE CONVERTED SUING IS LESS THAN THE 
RECEIVING FIELD. 
STARTING ADDRESS OF TW FIELD IN WHICH THE ASCII 

REPRESENTATION IS TO BE PLACED. 
NUMBER OF BYTES IN THE RECEIVING FIELD 

It U tll t t WIWWMMMWWWHt t MMt l lt Mtt tM l tlWt l MMMi t H t l * , 1 

2 1 NUMOUT: PROCEDURE (VALUE.. BASE.. LC, BUFADTj WIDTH) PUBLIC; 

3 2 DECLARE (VALUE, BUFADR) ADDRESS, 

4 2 DECLARE (BASE. LC< WIDTH. I) BVTEi 

5 2 DECLARE CHARS BASED BUFADR (1) BYTE 

6 2 DECLARE D!GITS<*> BVTE DATA <'M23-«78SABCDEF'); 

7 2 DO I = 1 TO WIDTH, 

3 3 CHAPS(WIDTH-I) = DIGITSCv'ALUE NuD BASE); 

9 3 VALUE = VALUE t ERSE: 

10 i END; 

U 2 1=8, 

12 2 DO WHILE CHARS(I) = 'V AND I < WIDTH - 1; 

13 3 QMR5CI) = LCi 

14 3 1 = 1+1; 

15 3 END, 

16 2 END NUMOUT; 

17 1 END, 



MODULE INFORMATION: 

CODE AREA SIZE = 80AAH 178D 
VARIABLE AREA SIZE = 8888H SD 
MAXIMUM STACK SIZE = 0886H 6D 
33 LINES READ 
8 FROGRAH ERROR(S) 

END' OF PL.T+-S8 COMPILATION 
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The iRMX 80 Executive will run on either iSBC 544 or 569 boards. These boards, 
which are 8085-based, are very similar in many respects (such as their interrupt 
structures, which are identical) to the iSBC 80/ 24 and 80/30 boards, so most of what 
this manual says about the iSBC 80/24 and 80/30 boards applies also to both the 
iSBC 544 and 569 boards. The purpose of this appendix is to document the few 
differences that apply to the iSBC 544 and 569 boards. 

iSBC 544 Intelligent Communications Controller 

The timer uses interrupt level A, rather than interrupt level 1. 

You must make the following hardware changes on the board: 

Disconnect jumper 32-33 
Connect jumper 33-34 
Connect jumper 67-68 
Set switches 1-6 to off 
Set switches 7-8 to on 

iSBC 569 Intelligent Digital Controller 

The timer uses interrupt level 2, rather than interrupt level 1. 
There is no on-board 8251 A to support the Terminal Handler. 



APPENDIX K 
ISBC 544 AND 569 
INTELLIGENT CONTROLLER BOARDS 
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APPENDIX L 
THE PATCH 80 UTILITY 



patch is an alteration of an object module. There are two basic kinds of patches: a 
replacement of existing code or data; and an addition of new code or data into 
existing code or data segments. 

PATCH80 is a utility that permits field insertion of patch routines into relocatable 
object modules. The modules to be patched must be in 8080 object module format 
and can be in library files. 

The PATCH80 utility is supplied, on the configuration/ utilities diskette, to be used 
in either of two ways. One way is to perform your own patches, either to your own 
modules or to iRMX 80 code (not recommended). The other way is to use the 
PATCH80 utility to implement patches as recommended by Intel. In the latter case, if 
it ever occurs, a complete list of instructions will be delivered to you, so knowledge of 
the PATCH80 utility is not required; you need only follow the instructions. In the 
former case, you must have thorough knowledge of both the PATCH80 utility and 
the module you propose to patch. 



NOTE 

If possible, you should try to charge your source code, rather than 
patching object code with the PATCH80 Utility. This methodology is 
consistent with recommended, self-documenting programming practices. 
In general, patching should be regarded as an emergency measure. 




If you attempt to implement your own patches to iRMX 80 code, you run 
the risk of fatally damaging that code. Be sure to make a backup copy 
before trying this. 



Use Environment 

The PATCH80 utility runs on an Intelle; Development System with the ISIS-II 
operating system. It requires 64K of RAM, at least two single- or double-density disk 
drives, and an operator's terminal. 



Using the PATCH 80 Utility 

You can invoke the PATCH 80 utility fram ISIS-II by entering :device: PATCH, 
followed by the name of the module which is to be patched. Some example 
invocations are 

>:F5: PATCH :F1:BADMOD.OBJ <CR> 

>:F5: PATCH :F1;MY.LIB(BADMOD.OBJ) <CR> 

When invoked, the utility creates a backup copy of the specified file. The backup 
copy has the same name as the original, except that it has the extension BAK. 
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The utility signals that it is ready by issuing the message 

PATCH-80 VERSION 1.0 
followed by its first prompt 

TYPE (PUBLIC, ABSOLUTE, EXTERNAL OR DATA): 

You respond by indicating which type of patch you want (the four types are described 
later); enter either the entire word or just the first letter. If you enter anything else, the 
utility displays the message 

PATCH TYPE UNRECOGNIZED 

and reissues the prompt. 

Next, the utility issues its second prompt 
NAME: 

You respond by entering the patch name, which consists of from one to six 
alphanumeric characters, the first of which must be either a letter or one of the 
special characters "?" or "@". If you enler an invalid string of characters or if you 
enter a name that is already in the symbol table for the module, the utility displays 
the message 

ILLEGAL NAME 

or 

NAME ALREADY DEFINED 

The purpose of the patch name is to provide you with a means of locating the patch 
and distinguishing it from other patches to the same module. The utility integrates 
the name into the code, just as if it had been present as PUBLIC data or a PUBLIC 
label declaration when the module was compiled or assembled. Therefore, if you 
subsequently use the ISIS-II LIB utility to get a list of the PUBLICs for the module, 
the name you entered in response to the "NAME:" prompt will be included in the list. 

Next, the utility issues its third prompt 
ADDRESS: 

You respond by entering the offset, in tht: code or data segment, of the location that 
is to be associated with the patch name. The first byte of the segment has offset 0. 
Your entry must be in hexadecimal and must be in the range OH to OFFFFH. If you 
enter an improper value, the utility displays the message 

HEX VALUE UNRECOGNIZED 

or 

HEX VALUE OUT OF RANGE (0-FFFF) 

or 

ADDRESS SPECIFIED IS BEYOND END OF MODULE 



Next, depending upon which type of patch you have specified, the utility might issue 
additional prompts. These prompts are described later, in the sections that describe 
the various kinds of patches. 

Finally, the utility issues the prompt 
PATCH (Y,N): 
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If you enter "Y", the patch is performed as you have defined it. If you enter "N", no 
patch is performed, and the data that you have entered since the last "TYPE" prompt 
is discarded. If you enter any other response, the message 

YES OR NO PLEASE 

is displayed, followed again by the "PATCH (Y,N):" prompt. When you successfully 
enter a "Y" or "N" response, the utility issues another 

TYPE (PUBLIC, ABSOLUTE, EXTERNAL OR DATA): 

prompt, after which you can define an additional patch. If you do not wish to define 
another patch, you can exit the PATCH80 utility by entering a carriage return. This 
is the only normal way of exiting the utility. 

The Absolute Patch 

An absolute patch is a byte-for-byte replacement of a contiguous string of bytes in 
the object module. After you respond to the "TYPE:", "NAME:", and "ADDRESS:" 
prompts, the utility issues the prompt 

DATA: 

You respond by entering a string of hexacecimal values, separated by commas, and 
terminated with a carriage return; each value must be in the range of OH through 
OFFH. The utility continues to issue the "DATA:" prompt until you resond with just 
a carriage return. In any absolute patch, you may enter a total of up to 255 values in 
response to the "DATA:" prompts. 

If you enter an invalid character, the message 
HEX VALUE UNRECOGNIZED 

is displayed, the data entered in response to the most recent "DATA:" prompt is 
discarded, and the "DATA:" prompt is reissued. If you enter a value that is larger 
than OFFH, the message 

HEX VALUE OUT OF RANGE (0- FF) 

is displayed, the data entered in respons; to the most recent "DATA:" prompt is 
discarded, and the "DATA:" prompt is reissued. If you enter too many values, the 
message 

DATA BUFFER EXCEEDED 

or 

ATTEMPT TO PATCH BEYOND END OF MODULE 

is displayed, all information entered since the most recent "TYPE" prompt is 
discarded, and the "TYPE" prompt is reissued. 

An example of dialogue defining an absolute patch is the following: 

TYPE (PUBLIC, ABSOLUTE, EXTERNAL OR DATA): A <CR> 

NAME: PATCH 1 <CR> 

ADDRESS: 6A <CR> 

DATA: 34,56,AF,098H,C3H,017 <CR> 

DATA: 17,SD,43 <CR> 

HEX VALUE UNRECOGNIZED 

DATA: 17,AD,43 <CR> 

DATA: <CR> 

ABSOLUTE DATA: 

34 56 AF 98 C3 17 17 AD 43 

ITEM COUNT: 9 

PATCH (Y,N): Y <CR> 
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In the example, the PATCH80 utility would write the values 34, 56, AF, 98, C3, 17, 
17, AD, and 43 at offsets 6A through 72 respectively. The data previously in those 
locations would be wiped out. Note thai the utility prints the contents of its data 
buffer so that you can verify its accuracy. 

The Public Patch 

A public patch associates the name you enter in response to the "NAME:" prompt 
with a location in the code segment, just as if the name had been present as a 
PUBLIC label at the time of compilation or assembly. 

The Data Patch 

A data patch is exactly like a PUBLIC patch, except that it associates the name with 
a location in the data segment. 

The External Patch 

An external patch is used when it is necessary to add code to the code segment, or 
when a contiguous section of code is to be replaced by a "repair module" of code. 
Figure L-l shows a main module along with a "repair code" module that is to be 
inserted between bytes, as indicated. The letters in the figure are for the explanation 
that follows. 



MODULE 



r 



CODE J 
SEGMENT A 



■-< 



>- CONSTANTS 



} 



C 



VcODE 



> 



DATA 



Figure L-l. A Main Modi le with a Repair Module 
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In order to implement the integration of tre repair module into the main module, the 
following things must be done: 

(1) A jump (A) to the repair module must be placed in the main module, and the 
destination of the jump (B) must be declared EXTERNAL in the main module 
and PUBLIC in the repair module. 

(2) The instruction that is overwritten by the jump instruction must, if it is to be 
executed, be relocated to the repair module (C). 

(3) Any data in the main module that is addressed in the repair module must be 
declared EXTERNAL in the repair module and PUBLIC in the main module. 

(4) A jump (D) back to the main module nust be included in the repair module, and 
the destination of the jump (E) must be declared EXTERNAL in the repair 
module and PUBLIC in the main nodule. 

The repair module is new, so it can be wiitten to include the necessary declarations 
and jump instruction, and therefore does not need to be patched. Use the PATCH80 
utility to make the necessary alterations to the main module, as follows. 

To declare the jump destination (E) PUBLIC, perform a public patch at the 
appropriate address. 

To declare the data PUBLIC, perform data patches at the appropriate addresses. 

To write the jump instruction (A) and tc declare the destination (B) of that jump 
EXTERNAL in the main module, perform an external patch. After you respond to 
the "ADDRESS:" prompt, the utility w 11 issue the external patch's only unique 
prompt 

EXTERNAL NAME: 

You respond by entering the name of the jumps destination, that is, the name that 
you declare to be PUBLIC in the repair module. The rules governing the formation 
of this name are the same as those for the name of the patch. If you violate the rules, 
the message 

ILLEGAL NAME 

is displayed and the "EXTERNAL NAME:" prompt is repeated. 

After you successfully enter the external name, you are ready to perform the patch. 
When you respond in the affirmative to the "PATCH (Y,N):" prompt, the utility 
places the jump instruction in the specified location and effectively declares 
EXTERNAL the name of the jump's destination. 

Because an external patch writes over ;ode in the main module, you must be 
extremely careful. Ideally, the (three-byte) jump instruction should be written over 
another three-byte instruction. If this is no t possible, it might be necessary to perform 
patches in addtion to those already described. 

NOTE 

Be sure that the jump instruction is not written over an instruction that 
references a relative address. If this were done, the linker would destroy the 
EXTERNAL declaration created by the external patch. In particular, the jump 
must not replace another jump insi ruction. 

In many cases, and particularly if you cho jse to write your repair module in PL/ M, 
it is desirable to patch in an interface routine (provided with PATCH80 as 
PTC1NT.ASM) by means of an external patch. In such a case, the interface routine 
calls the repair module. The example at th; end of the appendix illustrates this use of 
interface routines. 
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Another frequent requirement is that the repair code must have a larger stack than 
the one it inherits when called (or jumped to). This too is illustrated in the example. 

If you write your repair module in assembly language, use the ISIS-II command 

>SUBMIT ASMPTC(:DEV:ASM8() filename) 

to produce the required object file. On the other hand, if your repair code is in 
PL/M, use the command 

>SUBMIT PLMPTC(:DEV:PLM8C filename) 

instead. The SUBMIT files ASMPTC and PLMPTC are provided with PATCH80. 

After Patching 

When you have finished patching and have exited the PATCH80 utility, you must 
link together the modules and locate the resulting module. To do this, use the ISIS-II 
command 

LINK :dev:patchedmain,:dev:interfacemod,:dev:repairmod 
TO :dev:finalmain 

or 

LINK :dev:patchedmain,:dev:repairmod TO :dev:finalmain 
depending upon whether or not you are using an interface routine. 



An Example 

This example illustrates all of the types of patches. It concerns a main module that 
prints 

THIS IS MESSAGE LINE 1 
THIS IS MESSAGE LINE 2 
THIS IS MESSAGE LINE 3 
THIS IS MESSAGE LINE 4 

and then halts. We want to patch it sc that it will print 

THIS IS MESSAGE ALPHA. 
THIS IS PATCH 1 
THIS IS MESSAGE LINE 2 
THIS IS MESSAGE LINE 3 
THIS IS MESSAGE LINE 4 

before halting. 

We Will use an absolute patch to change 'LINE 1 " to "ALPHA.", and we will use an 
external patch (with supporting public ard data patches) to get "THIS IS PATCH 1 " 
to print. The external patch is to an asse mbly language interface routine ( INTER 1) 
which 

(1) saves the register contents, 

(2) calls the repair module (PATCH 1), which is written in PL/M, 

(3) performs the load immediate instruction that is overwritten by the jump 
instruction produced by the external patch, 

(4) restores the register contents, and 

(5) does a jump back to the main module. 
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The interface routine also has its own stack where it stores the register contents, 
manipulates the stack pointer before pushing and after popping. 

The repair module simply prints "THIS 15 PATCH 1" and returns. 



The Patching Sequence 

The steps required to implement this patch are the following. We assume that all of 
the required files, including the main module MAIN. OBJ, are on a diskette in drive 
1. 

(1) Use a text editor to enter the file INTER I. ASM (the interface routine). 

(2) Enter the command SUBMIT ASMPTC(:F1:INTERI.ASM). 

(3) Use the text editor to enter the file PATCH l.PEX (the repair module). 

(4) Enter the command SUBMIT PLMPTC(:F1:PATCH1.PEX). 

(5) Carry on the following dialogue with ihe PATCH80 utility. The comments are 
for your benefit and are not to be entered. 

>PATCH :F1:MAIN.OBJ Activate PATCH 80 
PATCH-80 VERSION 1.0 

TYPE (PUBLIC, ABSOLUTE, EXTERNAL OR DATA) A <CR> 

NAME: PTC1 <CR> ;I"his patch changes "LINE I" to 

ADDRESS: 10 <CR> "ALPHA." in the first line of 

DATA: 41, 4C, 50, 48, 41, 2E <CR> text printed by the main module. 
DATA: <CR> 

ABSOLUTE DATA: 

1 4C 50 48 41 2E 

ITEM COUNT: 6 

PATCH (Y,N): Y <CR> 

TYPE (PUBLIC, ABSOLUTE, EXTEiRNAL OR DATA): EXTERNAL <CR> 
NAME: PTC 2 <CR> ;This patches the interface 

ADDRESS: 74 <CR> routine. 
EXTERNAL NAME: INTER1 <CR> 
PATCH (Y,N): Y <CR> 

TYPE (PUBLIC, ABSOLUTE, EXTERNAL OR DATA): PUBLIC <CR> 
NAME: ENTRY1 <CR> :This patch makes public the 

ADDRESS: 77 <CR> reentry point in the main module. 

PATCH (Y,N): Y <CR> 

TYPE (PUBLIC, ABSOLUTE, EXTERNAL OR DATA): DATA <CR> 
NAME:PUBSTA <CR> :This patch makes public a data 

ADDRESS: <CR> byte that is known locally as 

PATCH (Y,N): Y <CR> STATUS 

TYPE (PUBLIC, ABSOLUTE, EXTERNAL OR DATA): <CR> 

Return to ISIS-II 

(6) Enter the command 

RENAME :F1:MAIN.OBJ TO :l : 1 :PTMAIN.OBJ 

(7) Enter the command 

LINK :F1:PTMAIN.OBJ,:F1:INTER1.0BJ,:F1:PATCH1.0BJ 
TO :F1:MAIN.OBJ 

The main module, MAIN. OBJ, has new been patched and is ready to be located. 
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The Modules 

This section contains listings of the main module, the interface module, and the 
repair code module. Note that the main £ nd repair code modules were compiled with 
the CODE and SYMBOLS switches on. This enables us to see which machine 
instructions were generated by the compiler and where each instruction is, relative to 
the beginning of the code or data segment. 

The Main Module 

1SIS-11 PL/M-bO V3.1 C0KP1LA110K OF MODULE MAIN 
OBJECT MODULE PLACED IN : Fl : M A I N .OB J 

COMPILER INVOKED BY: PLM80 :Fl:MAlN.l>LK CODE SYMBOLS 



/» 



main : 



THIS IS A SAMPLE MAIN MODULE TO DEMONS1 RATF HOk PATCH-BO WAY 
bE USED 10 LINK II. ADDITIONAL PL/M ROUTINES TO THIS EXISTING 
OBJECT MODULE. 

do; 



exit: procedukE external: 
end exit; 



• HIE: PhOCEuURE (AFlN.bOFFEK, COUNT, STATUS) EXTERNAL; 

DECLARE (hFIN, BUFFER, COUNT, STATUS) ADDRESS; 
END »R1TE; 

DECLARE AFTSOUT L: TERALLY 'U'; 
TcCLARE SIAlUb APHRESS; 



9 
1U 



OECLAPE RT LITERALLY 'OLH* ; 
DECLARE LF LITERALLY * OAH * ; 



11 
12 
13 
14 
lb 

16 



DECLARE STRING LIVERALLY '(») BYTE DATA'; 

DECLARE MESSAGF.S1 SIRING ('THIS IS MESSAGE LINE l',RT,LF); 

DECLARE MESSAGF.S2 STRING ('THIS IS MESSAGE LINE 2',RT,LF); 

DECLARE MESSAGES 3 STRING I'lHlS IS MESSAGE LINE 3',RT,LF); 

DECLARE MESSAGES* SIRING I'TKIS IS MESSAGE LINE 4',RT,LF); 

CALL KR1TE (AFTSOtlT, • MESSAGES 1 ,LFNGTH(MESSAGES1 ), .STATUS); 

; STATEMENT • 16 



00t>0 


310000 


LX1 


SP.PSTACRSORIGIN 


00b3 


UlOOOO 


LXI 


6, OH 


OUbfa 


Cb 


PUSH 


b ; 1 


U0b7 


010000 


LXI 


fa' , NESSAGEl 


OObA 


C5 


PUSH 


b ; 2 


OObB 


110000 


LXI 


D, STATUS 


U06E 


OllbOO 


LXI 


t ,1BH 


U071 


CDOOOO 


CALL 


kRITt 



17 



CALL KfcllE (AFTSOUT, 



ID 



1* 



007 4 
007 7 
007t> 
00 lb 
00 IC 
Villi 
00b2 



OOBb 
OObb 
00b* 
OObC 
OObD 
00«U 
00*3 



ooyb 

OOifA 

ooyi) 

00<»E 



010000 
C5 

OllbOO 
Cb 

l loooo 
01 1 boo 
CDOOOO 

CALL 

010000 
Cb 

013000 
Lb 

110000 
01 1 HOC 
CDOOoO 

ChLL 

01 0000 
Cb 

01 4bOO 
Cb 

110000 



LXI 

PUSH 

LXI 

PUSH 

LXI 

LXI 

CALL 



»R) TE 



.MESSAGES 2 .LENGTH (MESSAGES 2) , .STATUS) f 
J STATEMENT I 17 

COH 

b ; l 

b, MESSAGE 2 
b .- 2 

D, STATUS 
b.ltfh 
•.RITE 

(At 'I S0U1, .MESSAGES3,LFNGTH(MES5AGFS3) , .STATUS); 
; STATEMENT • lb 

B.OH 

b ; 1 

b , MESSAGE3 

b ; 2 

D, STATUS 
B, 1 bH 
»RJ Tt 

MR11E ( AFTSOU I , .MESSAGES 4 , LENG1 H ( K ESSA GES 4 ) , .STATUS); 

; STATEMENT » 19 

LXI b.OH 

push b ; l 

LXI b, MESSAGE4 

PUSH b ; 2 

LXI P, STATUS 



LXI 

PUSH 

LXI 

PUSH 

LXI 

LXI 

CALL 
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RMX/80 



The PATCH80 Utility 



OOaI 011BUO 
00*4 CLUOOO 



LX1 
CALL 



20 



21 



C/.lL txil; 



UOA7 CDOOOO 

end main; 

OUAA tb 
UUAh /c 



CALL 



HLl 



b,18n 
mlTE 



E KIT 



; STATtfE.NI I 20 



; STATEMENT I 21 



SYMbOL LISTING 



DEFh ADDH SIZE NAME, ATTRlbUTtS, vNU KEKEKENCES 



4 


OUOOH 


2 


AFIS 


AODkEiiS PARAMETER 


7 






AFJOUT 


LITERALLY 


4 


OOOOH 


2 


bUt FER 


ADPkEi.S PARAMETER 


4 


OUUOH 


2 


COUNT 


AUDkEi.S PARAMETER 


2 


OOOOH 




EXIT 


PKOCEI-URE EXTERN AL CO ) ST«CK = O0OOH 


10 






LF 


LITERALLY 



The Interface Module 

The listing of the interface module follows This module generates its own stack so 
that it will not overflow the main module's stack. The module also pushes the 
contents of several registers onto its stack before calling the repair module, and it 
restores those values to the registers after r;gaining control from the repair module. 
Note that it is not always necessary to restore all of the registers, depending upon the 
situation. 

Aineo :h:paiint.asm 



ISIS-1I 6080/8085 CACRO ASSEMBLER , V2.0 



INTER1 PAGE 



0000 212000 

000 1 / 10000 
VOO* DAOOOO 
OUt>» St 

oooa cjofoo 



si 



0012 JUEOO 
001S 2A2000 



OVM FS 
U01* C> 



SEO 

1 
2 
3 
4 
5 
6 
7 
» 
» 
10 
It 
12 
1) 
14 
IS 
I* 
17 
111 
If 
20 

21 

22 

C 23 
24 

C 25 
2* 
27 
2S 
29 

D 30 
31 
D 32 
33 
34 
35 
3» 
37 
30 



SOURCE STATEMENT 
NAME INTER1 



PUBLIC 
EXTRN 

; 
i 
I 
; 
• 
> 
i 

stksiz eou 

CONTXT EOU 
RECSPC EOU 

; 
i 

CSEC 

I 

INTER 1 : SHLD 
LXI 



UTERI 
ENTRY 1 



EQUATE STACK SIZE 





24 
6 



5AVEHL 

M.O 

SAVCRY 



SAVCRII OAO 

SIC 

I 

seistk: shlo 
UI 
LHLD 

I 

STKSPC SET 
I 

» 

PUSH 



SAVESP 

SP.LCLSTK 

SAVEHL 

COKTXT+StKSIZ 
PS* 



;PATCH-BO REPAIR CODE INTERFACE 



; DECLARE ENTRY POINT PUBLIC 
; DECLARE EXIT POINT EXTERNAL 



irOR REPAIR CODE 

IFOR RMX/80 CONTEXT SWITCH 

IFOR REGISTER SAVE 



isave ih.l] 

;set up for (h,l)=[sp) 

(carry sett yes - preserve it 

;ih,lj.cspi 

I5EI UP THE LOCAL STACK 

I(H,LJ«(SPI 
(RESTORE CARRY 

ISAVE ENTRY ISP] 
1SET UP LOCAL STACK 
7 RESTORE IH.L) 

! DECLARE STACK SPACE 



I SAVE REGISTERS AND FLAGS 



L-9 



The PATCH80 Utility 



RMX/80 



UOl A 05 




39 




PUSH 


D 


OW1E 




40 


STKSPC 


SET 


STKSPC* KfctaSPC 






41 


9 










42 


3 










43 


9 * * * 


PLACE 


ASSEHBLI LANGUAGE 






44 


$ 










45 


9 










46 




EATRN 


PATCH 1 


IrOlB COO 004 


» E 


47 




CALL 


PATCH 1 


ooie oioaoi 


1 


48 




LXl 


a#o 






49 


1 










t»0 


1 






V021 01 




bl 




POP 


D 


UU22 Ci 




62 




PUP 


B 


0023 rt 




S3 




POP 


PS8 






54 


1 










55 


I 






0024 222004 


* D 


56 




SHLO 


5AVEHL 






57 


I 










50 


t 










59 


1 






0027 ZA1C0 


t 


60 




LHLD 


SAVESP 


002A r* 




61 




SPHL 




9028 2*200 


I 


62 




laHLO 


6AVCHL 






69 


9 






002C C30001 


1 c 


64 




JHP 


CMTRT1 






65 


I 










66 












67 




DSEG 








68 


1 






001C 




69 




OS 


STKSPC 






70 


LCLSTft I 










71 


1 






0O02 




72 


SAVESPl 


DS 


2 






73 


SAVEHLX 


OS 


2 






74 


$ 










75 


t 










76 




CMD 





I DECLARE REFERENCE TO PATCH ROUTINE EXTERNAL 
ICALL THE REPAIR NODULE 

I DUPLICATE BYTES WRITTEN IN NAIN NODULE 
; RESTORE REGISTERS AND FLAGS 



l(H,L]*(SP] ON ENTRY 
I RESTORE ISP1 
| RESTORE (H,L1 

»EXIT TO MAIN NODULE 



PRESERVE SPACE FOR LOCAL STACK 



I8T0REACE FOR tSP) 
ISTOREAGE SPACE FOR CK.L1 



PUBLIC SIHBOLS 
INltRl C 0000 



EXIEKkAL SJ'bOLS 

EkIRIl E UOOO PATCH1 E 0000 



USER 5INB0LS 
CUNTXT A 0011 
SAVCHL D 0020 
RECSPC A 0006 



ENTRT1 E 0000 
SAVESP D 001C 
SAVCRT C OOBD 



INTERS C 00 10 
SETSTK C 00 If 



LCLSTK D 001E 
ETKSIZ A 0000 



PATCH! E 0000 
STKSPC A 001E 



ASSEMBLY CO»PLtlE, DO ERRORS 

The Repair Module 

The following is a listing of the repair module. 

IS15-11 H/«->l) CGftPILATlnn OF NODULE PE I 

UBJtCl KODULL PLACti lk <F1 : PATCH 1 .UBJ 

COMPILER 1MVUMSU BY: PLNBO IF1 S PATCH1 .PEX CO >E SINBOLS 



10 
11 



REX: 



1HIS IS THE FIRST PATCH TD BE INSERTED INTO THE NAIN PL/N 
foDULE. IT IS C0HP1LED A. A PL/N EXTERNAL 
»/ 

DO; 

kKITEl 



PROCEDURE ( AFTN , Bl IFFER f COUN T « 
DECLARE (AFIN.B 
END WRITE; 



EXTERNAL; 



PATCHlt PROCEDURE PUBLIC; 
; PROC PATCH 1 



; STATENENT • S 
0'; 



ooii oioooo 

0014 cs 



DECLARE AFTSOUT L TERALLY 
DECLARE STATUS ADDRESS; 

DECLARE RT LITERALLY *©DH*J 
DECLARE LF LITERALLY * OAH* ; 

DECLARE STRING LI "ERALLY '(*) BYTE DATA'; 

DECLARE NESSAGESP:. STRInC C'THIS IE PATCH l',RT,LF>; 

CALL MRITt ( AFT$Ol IT, .MESSAGES PI f LENGTH (MESSAGEtPl ) , .STATUS); 
; STATENENT • 12 

LXl B.OH 

PUSH B 1 1 



L-10 



RMX/80 
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outs oiuoog 

uom cs 

uuis uoooo 

uuic Ollluo 

uoir cpoouo 



LXl *,KESS»GI PI 

PUSH 6 | 2 

LXI D, STATUS 

LXI B.11H 

•mre 



11 2 END fATCNW 

0022 CO RET 
14 1 END PEX> 



J STATEMENT t 11 



6Y«bOL LISTING 



LEF N 


ADDR 


SIZE 


AljKlbOTfcS, ANl REfr El* EfcCES 


2 


OOOOK 


2 


AF1I. 


ADDRESS fARAKETEH 


b 






AFlDOl 


LITERALLY 


2 


OOOOH 


2 


BUFFER 


ADDRESS PARAMETER 


2 


OOOOH 


2 


COoM 


ADDRESS PARAMETER 








LF 


LI TERALLi 




OOOOH 




►iE*OkY 


eYIE thRAYlO) 


11 


OOOOH 


i ; 


MESSAGF PI 


6Y1E ARRAY (17) PAT A 


b 


001 1H 


it 


FATCH1 


PRuCEtUPt. PUbLlC SlACK=000oH 


1 


001 1H 




PEX 


PRUCEHURE STACK=0OO0H 


• 






Kl 


L11ER*LLY 


2 


OOOOH 


2 


STATUS 


ADORES S PARAPFTEK 


7 


OOOOh 


2 


S1A.TUS 


ADDRESS 


10 






STRING 


LITERALLY 


2 


OOOOH 




WRITE 


PROCEDURE EX'JERNAL(O) STACK=O0OOH 



MODULE 1 Nfr ORfcATlOd : 

CUDF AREA SIZE = 002JK 3SD 

VARIABLE AREA SIZE = U002n 2D 

KAXlfUM STACK SIZE = OOObH t>D 
2b LINtS READ 
O PROGRAM ERRORIS) 

END OF PL/M-HO COMPILATION 



L-ll 




INDEX 



absolute patch, L-3 

Accept Message operation, 2-3, 2-7, 2-32, 
3-5 

active Debugger, 6-1, 6-5 
address control options, 6-7, 6-8 
allocation of memory, 1-2, 5-1 
alter memory options, 6-7, 6-8 
Analog Handlers 

error conditions, 8-3 

functions, 8-1 

general, 1-2, 8-1 

hardware requirements, 8-1 

linking and locating, 8-18 

memory requirements, 8-1 

performance data, 8-3 

priority, 8-2 

request messages, 8-4, 8-7, 8-10, 8-13, 
8-15 

Analog Input Handler, 1-2, 8-1 
Analog Output Handler, 1-2, 8-1 
appending code, L-l, L-4 
application design, 3-1 
ASM PTC, L-6 
asynchronous operation, 1-3 
ATTR1B service, 7-5, 7-27, 7^5 
attributes, E-5 

batch system, 1-3 
baud rate search, F-7, F-9 
BEL character, 4-2 
block, E-l, E-2 
Boostrap Loader 

functions provided, 9-1 

general, 9-1 

hardware environment, 9-1 

hardware requirements, 9-1 

implementation, 9-1 

loadable file, 9-1 

loader system, 9-1 

memory requirements, 9-1 

program-controlled loading, 9-1 

software environment, 9-1 

using the loader, 9-1 
bootstrap loading, 9-1 
break sequence, 4-2 
breakpoint 

clearing a, 6-16 

exchange, 6-15, 6-17, 6-25 

execution, 6-15, 6-17, 6-25 

general, 6-15 

send, 6-15, 6-17 

setting a, 6-16, 6-25 

wait, 6-15, 6-17 
Breakpoint List. 6-13, 6-15, 6-18, 6-22 

display, 6-20 



breakpoint registers, 6-15 

display, 6-20 
Breakpoint Task, 6-13, 6-15, 6-18, 6-19, 
6-21 

display, 6-20 
breakpoint-register format, 6-16 
breakpoint-task format, 6-18 
buffering of input data, 1-7, 2-22 
buffers, 7-38, 7-44 
bus priority, F-l, F-5, F-6, F-9 

CAM, 3-17, 7-3 

CHANGE command, 6-6, 6-15, 6-16, 6-26 

clock, 2-18, 7-3, G-l, U-l 

Clock Initialize operation, G-2 

Clock Tick operation, 2-3, 2-8 

CLOSE service, 7-4, 7-23, 7-45 

code shared by more than one task, 3-5, 3-6 

coding 

general, J-8 

messages, 2-16, 3-6 

RMX/80 operations, 2-5 

user tasks, 1-8, 3-3, 3-5 
Command Line Interpreter 

commands, 10-1 

command line, 10-1 

command table, 10-2 

command tail, 10-1 

general, 1 0-1 

invocation, 10-1 

memory requirements, 10-1 

message, 10-2 

utilities, 10-3 
communication between tasks, 1-6 
concurrency, 1-4 

conditional allocation request, 5-3 
configuration, 1-1 1 

dynamic alterations of, 2-3 

example, J-9 

general, 2-3, 3-1, 3-8 

memory requirements, D-3 
context save, 1-6, 2-13, 2-14, 2-22 
Continue option, 6-17 
control commands, 4-10 
control structures, 1-10, 2-36 
control table, 4-13, 4-17 
control-C command, 4-2, 6-5, 6-12, 6-13 
control-O command, 4-12, 6-5, 6-13 
control-P command, 4-12 
control-Q command, 4-12, 6-5, 6-13 
control-R command, 4-3, 4-11, 6-5 
control-S command, 4-12, 6-5, 6-13 
control-X command, 4-1 1 
control-Z command. 4-1 1 
controller-addressable RAM, 7-3, 9-2 



Index-1 



controllers, 7-3 

COPY utility, 10-3, 10-6 

carriage return (CR) character, 4-1 1 

Create Exchange operation, 2-4, 2-9, 2-31, 

2-35, 3-10 
Create Table, 2-30 

Create Task operation, 2-4, 2-8, 2-31, 3-5 

data block, E-2, E-3 

data patch, L-4 

data transfer services, 7-1 

deadlock, H-l 

Debugger 

active, 6-1, 6-5 

capabilities, 6-1 

commands, 6-4, 6-6, 6-7 

exchanges, 4-4, 6-3, 

general, 1-2, 2-1, 6-1, 1-1 

hardware requirements, 6-2 

memory mapping of code, 6-3 

memory requirements, 6-2 

passive, 6-1, 6-5 

priority, 6-23 

relationship to Terminal Handler, 6-2, 

6- 3 

debugging suggestions, 3-9, 6-23, 6-24, J-10 
DEFINE command, 6-6, 6-14, 6-19, 6-21 
Delay List 

display, 6-10 

general, 1-8 
DELETE service, 7-5, 7-24, 7-45 
Delete Exchange operation, 2-4, 2-10 
Delete Task operation, 2-4, 2-10 
DEMO file, 1-2 

Demonstration System, 1-3, 3-2, 6-4, A-5, 

G-2, G-5, I- 1 
Descriptor List, 1-10 
descriptors for exchanges, 1-10 
descriptors for tasks, 1-10 
designing a system, 3-1, J-6 
details of a system operation, 2-30 
DI instruction, 2-26, 3-6 
direct memory access, 7-3 
directory, E-5 

directory maintenance services, 7-1 
DIRECTORY utility, 10-3, 10-6 
Disable Level operation, 2-4, 2-9, 2-26, 2-27 
Disk File System 

buffer allocation, 7-44 

exchanges, 7-4, 7-5, 7-6, 7-7 

file structure, 7-19, E-l 

general, 1-2, 7-1, 7-4 

hardware requirements, 7-3 

memory requirements, 7-3 

service requests, 7-8 

service tasks, 7-42, 7-44 

services, 7-1, 7-4, 7-5, 7-10, 7-14, 7-16, 

7- 18, 7-23, 7-24, 7-25, 7-27, 7-29, 
7-32, 7-34 

diskette files, (RMX/80 product) A-l, A-5 
disks, 7-1, 7-3, 9-1, E-l 



DISKIO service, 7-2, 7-5, 7-34, 7-45, 9-1, 
9-2 

DISPLAY command, 6-6, 6-19, 6-25 

EI instruction, 2-22, 3-6 

Enable Level operation, 2-4, 2-11, 2-19, 

2-26, 2-27, 2-35 
End Interrupt operation, 2-4, 2-11, 2-22 
error codes 

Disk File System, 7-41 

Terminal Handler, 4-7, 4-9 
error messages (Debugger), 6-23 
escape (ESC) character, 4-1 1 
example of RMX/80 system, J-l 
exchange address, 2-32, 3-5 
exchange breakpoint, 6-15, 6-17, 6-25 
Exchange Descriptor 

display, 6-1 1, 6-12 

general, I -10, 2-33 
Exchange List display, 6-10 
exchanges 

Analog Handlers, 8-2 

configuration of, 3-2 

Debugger, 4-4 

deletion of, 2-4, 2-10 

descriptors, 1-10, 2-31, 2-33 
example, 2-34 

Disk File System, 7-4, 7-5, 7-6, 7-7 
dynamic creation of, 2-4, 2-9, 2-31, 2-35 
fields of messages, 2-16 
Free Space Manager, 5-2 
general, 1-6 

interrupt type, 1-6, 2-19 

message type, 1-6 

queueing at, 1-6 

Terminal Handler, 4-3, 4-4 
exclusive access to code, 3-6 
EXECUTE command, 6-5, 6-13, 6-24 
execution breakpoint, 6-15, 6-17, 6-25 
Executive diskette, A-l, D-l, D-2 
expression (in Debugger commands), 6-6 
extensions, 1-1 

Extensions diskette, A-5, D-2 
external patch, L-4 
external reference resolution, 1-3, 3-9 
external symbols, 1-3, 3-4, B-l 

File Name Block (FNB), 7-9 
FORMAT command, 6-5, 6-11 
FORMAT service, 7-2, 7-5, 7-32, 7-45 
FORMAT utility, 10-3, 10-6 
Free Space Manager 

acknowledgement of request, 5-4 

allocated message, 5-4 

allocation algorithm, 5-5 

allocation exchange, 5-2 

allocation request, 5-3, 5-4 

blocks as messages, 5-2, 5-4, 5-5 

coding examples, 5-6 

conditional requests, 5-3 
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contiguous blocks, 5-3 
examples, 5-6, 5-8 
format of allocated blocks, 5-4 
freeing memory, 5-6 
general, 1-2, 5-1, 1-1 
hardware requirements, 5-1 
initialization, 5-2 
lockout, 5-4 

memory requirements, 5-1 
messages, 5-3, 5-4 
minimizing overhead, 5-3, 5-6 
priority considerations, 5-5 
reclamation, 5-2, 5-6 
reclamation exchange, 5-2 
size of blocks, 5-2 
timing considerations, 5-5 
unconditional requests, 5-4 
full Terminal Handler, 4-1, 4-2 

GET command, 1-3 

GO command, 6-6, 6-15, 6-21 

hardware 

checkout, 3-2, 6-4 
considerations 

iSBC 80/ 10, 2-2, F-6 

iSBC 80/ 10B, 2-2, F-8 

iSBC 80/20. 2-2, F-l 

iSBC 80/24, 2-2, 

iSBC 80/30, 2-2, F-5 
general, 3-2, 4-1, 5-1, 6-2, 7-3, 8-1, 9-1, 
F-l 

interface for terminal, 2-2 
interrupt levels, 2-17 
header block, E-2 

HOME EXCHANGE field, 2-16, 3-6 

ICE-80, 1-2, 3-1, 6-1, 6^, 6-16, 6-23, 7-3, 

F-2, F-S F-5, F-7, F-9 
ICE-85, 1-2, 3-1, 6-1, 6-4, 6-16, 6-23, 7-3, 

F-5, F-6 
idle tasks, 2-17, 2-18 
IET, 2-31 

implementing a system, 3-1 
INCLUDE files 

general, 1-3, 3-5 

PL/M, A-2, A-6 
Initial Exchange Table, 2-31 
Initial Task Table, 2-31 
initialization 

Free Space Manager, 5-2 

system, 3-5 
input-output Terminal Handler, 4-1, 6-2, 
10-1 

Intellec Development System, 3-1, 6-1, 7-3, 

F-3, F-5, F-7, F-9, 1-1, L-I 
Interactive Configuration Utility, 2-1, 2-3 
interleaving factor, E-4 
Interrupt Exchange Descriptor, 2-35 
interrupt handling, 2-19, 2-26 
Interrupt Initialize operation, G-3 



interrupt polling routines, 2-13, 2-27, 7-7 
Interrupt Send operation, 2-4, 2-12, 2-21, 

2-26, 2-27, 2-28 
interrupt service routines 

general, 2-21 

iSBC 80/10, 1-1, 2-27 
example, 2-28 

iSBC 80/ 10B, 1-1, 2-27 
example, 2-28 

iSBC 80/20, 1-1,2-21 
example, 2-23 

iSBC 80/24, 1-1, 2-25 

iSBC 80/30, 1-1, 2-25 
interrupts 

disabling, 24, 2-9, 2-26, 2-27 

enabling, 2-4, 2-11, 2-19, 2-26, 2-27, 2-35 

exchange descriptors, 1-10, 2-35 
example, 2-35 

exchanges, 1-6, 2-19, 4-2 

general, 3-6, 9-4 

missed, 2-20, 2-21, 2-36 

iSBC 80/10, 2-17, 3-6, F-6 

iSBC 80/ 10B, 2-17, 3-6, F-8 

iSBC 80/20, 2-17, 3-6, F-l 

iSBC 80/24, 2-17, 3-6, F^ 

iSBC 80/30, 2-17, 3-6, F-5 

polling routines, 2-13, 2-27 
intertask communication, 1-6 
iSBC 104, 3-18, G-l, G-5, I-I 
iSBC 108, G-l, G-5, 1-1 
iSBC 116, G-l, G-5, 1-1 
iSBC 201, 7-3 
iSBC 202, 7-3 
iSBC 204, 7-3, 7-8 
iSBC 206, 7-3, 7-8, 7-35 
iSBC 517, G-l, G-5, 1-1 
iSBC 544, K-l 
iSBC 569, K-l 
iSBC 711, 8-1 
iSBC 724, 8-1 
iSBC 732, 8-1 
iSBC 80/10 

general, 2-19, 6-2, F-6, G-I 

interrupts, 2-17, 2-27, 3-6, 7-7, G-6 

hardware considerations, F-6 

time base considerations, G-l 
iSBC 80/10B 

general, 2-1, 6-2, F-8 

hardware considerations, F-8 

interrupts, 2-17, 2-27, 3-6, F-8 

time base considerations, F-8, 6-1 
iSBC 80/20 

general, 2-1, 6-2, F-l 

hardware considerations, F-I 

interrupts, 2-17, 2-21, 3-6, F-l 
iSBC 80/24 

general, 2-1, 6-2, F-4 
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